qilisdk 0.1.8__cp312-cp312-manylinux_2_28_x86_64.whl

qilisdk/experiments/__init__.py

@@ -0,0 +1,36 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from .experiment_functional import ExperimentFunctional, RabiExperiment, T1Experiment, T2Experiment, TwoTonesExperiment
+from .experiment_result import (
+    Dimension,
+    ExperimentResult,
+    RabiExperimentResult,
+    T1ExperimentResult,
+    T2ExperimentResult,
+    TwoTonesExperimentResult,
+)
+
+__all__ = [
+    "Dimension",
+    "ExperimentFunctional",
+    "ExperimentResult",
+    "RabiExperiment",
+    "RabiExperimentResult",
+    "T1Experiment",
+    "T1ExperimentResult",
+    "T2Experiment",
+    "T2ExperimentResult",
+    "TwoTonesExperiment",
+    "TwoTonesExperimentResult",
+]

qilisdk/experiments/experiment_functional.py

@@ -0,0 +1,212 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from abc import ABC
+from typing import TYPE_CHECKING, ClassVar, Generic, TypeVar
+
+from qilisdk.experiments.experiment_result import (
+    ExperimentResult,
+    RabiExperimentResult,
+    T1ExperimentResult,
+    T2ExperimentResult,
+    TwoTonesExperimentResult,
+)
+from qilisdk.functionals.functional import Functional
+from qilisdk.yaml import yaml
+
+if TYPE_CHECKING:
+    import numpy as np
+
+TResult_co = TypeVar("TResult_co", bound=ExperimentResult, covariant=True)
+
+
+@yaml.register_class
+class ExperimentFunctional(Functional, ABC, Generic[TResult_co]):
+    """Abstract base class for single-qubit experiment functionals.
+
+    This class serves as a generic interface for defining quantum
+    characterization experiments such as Rabi or T1. Each subclass
+    specifies a concrete `ExperimentResult` type and the corresponding
+    sweep parameters.
+    """
+
+    def __init__(self, qubit: int) -> None:
+        """Initialize the experiment functional.
+
+        Args:
+            qubit (int): The physical qubit index on which the experiment is performed.
+        """
+        self._qubit = qubit
+
+    @property
+    def qubit(self) -> int:
+        """The physical qubit index on which the experiment is performed.
+
+        Returns:
+            int: Index of the qubit.
+        """
+        return self._qubit
+
+
+@yaml.register_class
+class RabiExperiment(ExperimentFunctional[RabiExperimentResult]):
+    """Rabi experiment functional for a single qubit.
+
+    This functional defines a standard Rabi oscillation experiment where
+    the drive pulse duration is swept to measure the oscillatory response
+    of the qubit under continuous driving.
+    """
+
+    result_type: ClassVar[type[RabiExperimentResult]] = RabiExperimentResult
+    """Result type returned by this functional."""
+
+    def __init__(self, qubit: int, drive_duration_values: np.ndarray) -> None:
+        """Initialize a Rabi experiment functional.
+
+        Args:
+            qubit (int): The physical qubit index on which the experiment is performed.
+            drive_duration_values (np.ndarray): Array of drive pulse durations (in nanoseconds)
+                used to sweep the experiment.
+        """
+        super().__init__(qubit=qubit)
+        self._drive_duration_values = drive_duration_values
+
+    @property
+    def drive_duration_values(self) -> np.ndarray:
+        """Drive pulse duration sweep values.
+
+        Returns:
+            np.ndarray: The set of drive durations (in nanoseconds) used in the Rabi experiment.
+        """
+        return self._drive_duration_values
+
+
+@yaml.register_class
+class T1Experiment(ExperimentFunctional[T1ExperimentResult]):
+    """T1 relaxation experiment functional for a single qubit.
+
+    This functional defines a standard T1 (energy relaxation) experiment,
+    where the delay between excitation and measurement is varied to extract
+    the relaxation time constant of the qubit.
+    """
+
+    result_type: ClassVar[type[T1ExperimentResult]] = T1ExperimentResult
+    """Result type returned by this functional."""
+
+    def __init__(self, qubit: int, wait_duration_values: np.ndarray) -> None:
+        """Initialize a T1 experiment functional.
+
+        Args:
+            qubit (int): The physical qubit index on which the experiment is performed.
+            wait_duration_values (np.ndarray): Array of waiting times (in nanoseconds)
+                between excitation and measurement.
+        """
+        super().__init__(qubit=qubit)
+        self._wait_duration_values: np.ndarray = wait_duration_values
+
+    @property
+    def wait_duration_values(self) -> np.ndarray:
+        """Waiting time sweep values.
+
+        Returns:
+            np.ndarray: The set of delay durations (in nanoseconds) used in the T1 experiment.
+        """
+        return self._wait_duration_values
+
+
+@yaml.register_class
+class T2Experiment(ExperimentFunctional[T2ExperimentResult]):
+    """T2 dephasing experiment functional for a single qubit.
+
+    This functional defines a Ramsey/spin-echo style T2 experiment, where
+    the free-evolution delay between phase-sensitive pulses is swept to
+    extract the qubit coherence time.
+    """
+
+    result_type: ClassVar[type[T2ExperimentResult]] = T2ExperimentResult
+    """Result type returned by this functional."""
+
+    def __init__(self, qubit: int, wait_duration_values: np.ndarray) -> None:
+        """Initialize a T2 dephasing experiment functional.
+
+        Args:
+            qubit (int): The physical qubit index on which the experiment is performed.
+            wait_duration_values (np.ndarray): Array of free-evolution delays
+                (in nanoseconds) between the phase-sensitive pulses.
+        """
+        super().__init__(qubit=qubit)
+        self._wait_duration_values: np.ndarray = wait_duration_values
+
+    @property
+    def wait_duration_values(self) -> np.ndarray:
+        """Free-evolution delay sweep values.
+
+        Returns:
+            np.ndarray: The set of delay durations (in nanoseconds) used to estimate T2.
+        """
+        return self._wait_duration_values
+
+
+@yaml.register_class
+class TwoTonesExperiment(ExperimentFunctional[TwoTonesExperimentResult]):
+    """Two-tone spectroscopy functional for a single qubit.
+
+    Sweeps a drive tone frequency while monitoring the readout tone to
+    identify the qubit transition frequency.
+    """
+
+    result_type: ClassVar[type[TwoTonesExperimentResult]] = TwoTonesExperimentResult
+    """Result type returned by this functional."""
+
+    def __init__(self, qubit: int, frequency_start: float, frequency_stop: float, frequency_step: float) -> None:
+        """Initialize a two-tone spectroscopy functional.
+
+        Args:
+            qubit (int): The physical qubit index on which the experiment is performed.
+            frequency_start (float): Starting frequency of the swept drive tone (in Hz).
+            frequency_stop (float): Ending frequency of the swept drive tone (in Hz).
+            frequency_step (float): Frequency increment between sweep points (in Hz).
+        """
+        super().__init__(qubit=qubit)
+        self._frequency_start: float = frequency_start
+        self._frequency_stop: float = frequency_stop
+        self._frequency_step: float = frequency_step
+
+    @property
+    def frequency_start(self) -> float:
+        """Start frequency for the drive tone sweep.
+
+        Returns:
+            float: Starting frequency of the drive tone (in Hz).
+        """
+        return self._frequency_start
+
+    @property
+    def frequency_stop(self) -> float:
+        """Stop frequency for the drive tone sweep.
+
+        Returns:
+            float: Ending frequency of the drive tone (in Hz).
+        """
+        return self._frequency_stop
+
+    @property
+    def frequency_step(self) -> float:
+        """Step size for the drive tone sweep.
+
+        Returns:
+            float: Frequency increment between sweep points (in Hz).
+        """
+        return self._frequency_step

qilisdk/experiments/experiment_result.py

@@ -0,0 +1,247 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from pathlib import Path
+from typing import ClassVar
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.figure import Figure
+
+from qilisdk.functionals.functional_result import FunctionalResult
+from qilisdk.yaml import yaml
+
+
+@yaml.register_class
+class Dimension:
+    """Represents a labeled dimension in an experiment sweep.
+
+    A `Dimension` defines one or more sweep parameters, such as drive
+    amplitude, frequency, or delay time, together with their associated
+    numerical values.
+
+    Attributes:
+        labels (list[str]): Human-readable labels for the sweep parameters.
+        values (list[np.ndarray]): Numeric arrays representing the values
+            corresponding to each label.
+    """
+
+    def __init__(self, labels: list[str], values: list[np.ndarray]) -> None:
+        """Initialize a Dimension object.
+
+        Args:
+            labels (list[str]): Labels describing each dimension (e.g. ``["Drive amplitude"]``).
+            values (list[np.ndarray]): Numerical arrays for the corresponding parameter values.
+        """
+        self.labels = labels
+        self.values = values
+
+
+@yaml.register_class
+class ExperimentResult(FunctionalResult):
+    """Base class for storing and visualizing experiment results.
+
+    This class defines common utilities for handling experimental data,
+    including computation of S21 parameters and automatic 1D or 2D plotting.
+    Subclasses provide specific sweep parameters and plot titles.
+    """
+
+    plot_title: ClassVar[str]
+    """Default plot title; subclasses provide the concrete label."""
+
+    def __init__(self, qubit: int, data: np.ndarray, dims: list[Dimension]) -> None:
+        """Initialize an experiment result.
+
+        Args:
+            qubit (int): The qubit index on which the experiment was performed.
+            data (np.ndarray): Raw experimental data array.
+            dims (list[Dimension]): Sweep dimensions of the experiment.
+        """
+        self.qubit = qubit
+        self.data = data
+        self.dims = dims
+
+    @property
+    def s21(self) -> np.ndarray:
+        """Complex S21 transmission parameter.
+
+        Returns:
+            np.ndarray: The complex-valued S21 response computed as ``Re + i * Im``.
+        """
+        return self.data[..., 0] + 1j * self.data[..., 1]
+
+    @property
+    def s21_modulus(self) -> np.ndarray:
+        """Magnitude of the S21 parameter.
+
+        Returns:
+            np.ndarray: The absolute value of the S21 parameter.
+        """
+        return np.abs(self.s21)
+
+    @property
+    def s21_db(self) -> np.ndarray:
+        """Magnitude of S21 in decibels (dB).
+
+        Returns:
+            np.ndarray: ``20 * log10(abs(S21))`` expressed in dB.
+        """
+        return 20 * np.log10(self.s21_modulus)
+
+    def plot(self, save_to: str | None = None) -> None:
+        """Plot the S21 parameter from experiment results.
+
+        Automatically detects whether the dataset is 1D or 2D and creates
+        the appropriate figure. Optionally saves the figure to disk.
+
+        Args:
+            save_to (str | None): Optional path or directory to save the
+                generated plot. If a directory is provided, the filename is
+                automatically generated as ``{plot_title}_qubit{qubit}.png``.
+
+        Raises:
+            NotImplementedError: If the experiment data has more than 2 dimensions.
+        """
+
+        def save_figure(figure: Figure, save_to: str | Path) -> None:
+            save_to = Path(save_to)
+
+            # If a directory was given, append the default filename
+            if save_to.is_dir():
+                save_to /= f"{self.plot_title}_qubit{self.qubit}.png"
+
+            save_to.parent.mkdir(parents=True, exist_ok=True)
+            figure.savefig(save_to)
+
+        def plot_1d(s21: np.ndarray, dims: list[Dimension]) -> None:
+            """Plot 1d"""
+            x_labels, x_values = dims[0].labels, dims[0].values
+
+            fig, ax1 = plt.subplots()
+            ax1.set_title(f"{self.plot_title} - Qubit {self.qubit}")
+            ax1.set_xlabel(x_labels[0])
+            ax1.set_ylabel(r"$|S_{21}|$")
+            ax1.plot(x_values[0], s21, ".")
+
+            if len(x_labels) > 1:
+                # Create secondary x-axis
+                ax2 = ax1.twiny()
+
+                # Set labels
+                ax2.set_xlabel(x_labels[1])
+                ax2.set_xlim(min(x_values[1]), max(x_values[1]))
+
+                # Set tick locations
+                ax2_ticks = np.linspace(min(x_values[1]), max(x_values[1]), num=6)
+                ax2.set_xticks(ax2_ticks)
+
+                # Force scientific notation
+                ax2.ticklabel_format(axis="x", style="sci", scilimits=(-3, 3))
+
+            if save_to:
+                save_figure(fig, save_to)
+
+            plt.show()
+
+        # pylint: disable=too-many-locals
+        def plot_2d(s21: np.ndarray, dims: list[Dimension]) -> None:
+            """Plot 2d"""
+            x_labels, x_values = dims[0].labels, dims[0].values
+            y_labels, y_values = dims[1].labels, dims[1].values
+
+            # Create x and y edge arrays by extrapolating the edges
+            x_edges = np.linspace(x_values[0].min(), x_values[0].max(), len(x_values[0]) + 1)
+            y_edges = np.linspace(y_values[0].min(), y_values[0].max(), len(y_values[0]) + 1)
+
+            fig, ax1 = plt.subplots()
+            ax1.set_title(f"{self.plot_title} - Qubit {self.qubit}")
+            ax1.set_xlabel(x_labels[0])
+            ax1.set_ylabel(y_labels[0])
+
+            # Force scientific notation
+            ax1.ticklabel_format(axis="both", style="sci", scilimits=(-3, 3))
+
+            mesh = ax1.pcolormesh(x_edges, y_edges, s21.T, cmap="viridis", shading="auto")
+            fig.colorbar(mesh, ax=ax1)
+
+            if len(x_labels) > 1:
+                # Create secondary x-axis
+                ax2 = ax1.twiny()
+
+                # Set labels
+                ax2.set_xlabel(x_labels[1])
+                ax2.set_xlim(min(x_values[1]), max(x_values[1]))
+
+                # Set tick locations
+                ax2_ticks = np.linspace(min(x_values[1]), max(x_values[1]), num=6)
+                ax2.set_xticks(ax2_ticks)
+
+                # Force scientific notation
+                ax2.ticklabel_format(axis="x", style="sci", scilimits=(-3, 3))
+            if len(y_labels) > 1:
+                ax3 = ax1.twinx()
+                ax3.set_ylabel(y_labels[1])
+                ax3.set_ylim(min(y_values[1]), max(y_values[1]))
+
+                # Set tick locations
+                ax3_ticks = np.linspace(min(y_values[1]), max(y_values[1]), num=6)
+                ax3.set_xticks(ax3_ticks)
+
+                # Force scientific notation
+                ax3.ticklabel_format(axis="y", style="sci", scilimits=(-3, 3))
+
+            if save_to:
+                save_figure(fig, save_to)
+
+            plt.tight_layout()
+            plt.show()
+
+        n_dimensions = len(self.s21_modulus.shape)
+        if n_dimensions == 1:
+            plot_1d(self.s21_modulus, self.dims)
+        elif n_dimensions == 2:  # noqa: PLR2004
+            plot_2d(self.s21_modulus, self.dims)
+        else:
+            raise NotImplementedError("3D and higher dimension plots are not supported yet.")
+
+
+@yaml.register_class
+class RabiExperimentResult(ExperimentResult):
+    """Result container for Rabi experiments."""
+
+    plot_title: ClassVar[str] = "Rabi"
+    """Default title for Rabi experiment plots."""
+
+
+@yaml.register_class
+class T1ExperimentResult(ExperimentResult):
+    """Result container for T1 relaxation experiments."""
+
+    plot_title: ClassVar[str] = "T1"
+    """Default title for T1 experiment plots."""
+
+
+@yaml.register_class
+class T2ExperimentResult(ExperimentResult):
+    """Result container for T2 dephasing experiments."""
+
+    plot_title: ClassVar[str] = "T2"
+    """Default title for T2 experiment plots."""
+
+
+@yaml.register_class
+class TwoTonesExperimentResult(ExperimentResult):
+    """Result container for TwoTones experiments."""
+
+    plot_title: ClassVar[str] = "TwoTones"
+    """Default title for TwoTones experiment plots."""

qilisdk/functionals/__init__.py

@@ -0,0 +1,29 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .sampling import Sampling
+from .sampling_result import SamplingResult
+from .time_evolution import TimeEvolution
+from .time_evolution_result import TimeEvolutionResult
+from .variational_program import VariationalProgram
+from .variational_program_result import VariationalProgramResult
+
+__all__ = [
+    "Sampling",
+    "SamplingResult",
+    "TimeEvolution",
+    "TimeEvolutionResult",
+    "VariationalProgram",
+    "VariationalProgramResult",
+]

qilisdk/functionals/functional.py

@@ -0,0 +1,39 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from abc import ABC
+from typing import ClassVar, Generic, TypeVar
+
+from qilisdk.core.parameterizable import Parameterizable
+from qilisdk.functionals.functional_result import FunctionalResult
+
+TResult_co = TypeVar("TResult_co", bound=FunctionalResult, covariant=True)
+
+
+class Functional(ABC):
+    """
+    Abstract interface for executable routines that return a :class:`FunctionalResult`.
+
+    Subclasses detail the concrete `result_type` they generate.
+    """
+
+    result_type: ClassVar[type[FunctionalResult]]
+    """Concrete :class:`~qilisdk.functionals.functional_result.FunctionalResult` subclass returned."""
+
+
+class PrimitiveFunctional(Parameterizable, Functional, ABC, Generic[TResult_co]):
+    """
+    Base class for functionals backed by a :class:`~qilisdk.core.parameterizable.Parameterizable` object.
+    """

qilisdk/functionals/functional_result.py

@@ -0,0 +1,18 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from qilisdk.core.result import Result
+
+
+class FunctionalResult(Result):
+    """Base class for artifacts produced by executing a :class:`Functional`."""

qilisdk/functionals/sampling.py

@@ -0,0 +1,89 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from typing import ClassVar
+
+from qilisdk.core.types import RealNumber
+from qilisdk.core.variables import ComparisonTerm
+from qilisdk.digital.circuit import Circuit
+from qilisdk.functionals.functional import PrimitiveFunctional
+from qilisdk.functionals.sampling_result import SamplingResult
+from qilisdk.yaml import yaml
+
+
+@yaml.register_class
+class Sampling(PrimitiveFunctional[SamplingResult]):
+    """
+    Execute a digital circuit and collect bitstring samples.
+
+    Example:
+        .. code-block:: python
+
+            from qilisdk.digital.circuit import Circuit
+            from qilisdk.functionals.sampling import Sampling
+
+            circuit = Circuit(nqubits=2)
+            circuit.h(0)
+            sampler = Sampling(circuit, nshots=1024)
+    """
+
+    result_type: ClassVar[type[SamplingResult]] = SamplingResult
+
+    def __init__(self, circuit: Circuit, nshots: int = 1000) -> None:
+        """
+        Args:
+            circuit (Circuit): Circuit to execute for sampling.
+            nshots (int, optional): Number of repetitions used to estimate probabilities. Defaults to 1000.
+        """
+        self.circuit = circuit
+        self.nshots = nshots
+
+    @property
+    def nparameters(self) -> int:
+        """Return the number of parameters exposed by the underlying circuit."""
+        return self.circuit.nparameters
+
+    def set_parameters(self, parameters: dict[str, RealNumber]) -> None:
+        """Assign a subset of circuit parameters provided by label."""
+        self.circuit.set_parameters(parameters)
+
+    def get_parameters(self) -> dict[str, RealNumber]:
+        """Return a mapping of all circuit parameters to their current value."""
+        return self.circuit.get_parameters()
+
+    def get_parameter_names(self) -> list[str]:
+        """Return circuit parameter labels in deterministic order."""
+        return list(self.circuit.get_parameters().keys())
+
+    def get_parameter_values(self) -> list[RealNumber]:
+        """Return the current parameter values following ``get_parameter_names`` order."""
+        return list(self.circuit.get_parameters().values())
+
+    def set_parameter_values(self, values: list[float]) -> None:
+        """Update all circuit parameters using the order defined by ``get_parameter_names``."""
+        self.circuit.set_parameter_values(values)
+
+    def get_parameter_bounds(self) -> dict[str, tuple[float, float]]:
+        """Return lower and upper bounds registered for each circuit parameter."""
+        return self.circuit.get_parameter_bounds()
+
+    def set_parameter_bounds(self, ranges: dict[str, tuple[float, float]]) -> None:
+        """Update the admissible range for selected circuit parameters."""
+        self.circuit.set_parameter_bounds(ranges)
+
+    def get_constraints(self) -> list[ComparisonTerm]:
+        """Expose parameter constraints defined on the circuit.
+        Returns:
+            list[ComparisonTerm]: a list of constraints on the circuit parameters.
+        """
+        return self.circuit.get_constraints()