qilisdk 0.1.0__py3-none-any.whl

qilisdk/__init__.py

@@ -0,0 +1,47 @@
+# 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.
+
+import sys
+from typing import List
+
+from qilisdk.common import Algorithm, Model, Optimizer, Result
+
+from ._optionals import ImportedFeature, OptionalFeature, Symbol, import_optional_dependencies
+
+# Put your always-available, core symbols here
+__all__ = ["Algorithm", "Model", "Optimizer", "Result"]
+
+# Define your optional features
+OPTIONAL_FEATURES: List[OptionalFeature] = [
+    OptionalFeature(
+        name="cuda-backend",
+        dependencies=["cudaq"],
+        symbols=[Symbol(path="qilisdk.extras.cuda.cuda_backend", name="CudaBackend")],
+    ),
+    OptionalFeature(
+        name="qaas",
+        dependencies=["httpx", "keyring", "pydantic", "pydantic-settings"],
+        symbols=[Symbol(path="qilisdk.extras.qaas.qaas_backend", name="QaaSBackend")],
+    ),
+    # Add more OptionalFeature() entries for other extras if needed
+]
+
+current_module = sys.modules[__name__]
+
+# Dynamically import (or stub) each feature's symbols and attach them
+for feature in OPTIONAL_FEATURES:
+    imported_feature: ImportedFeature = import_optional_dependencies(feature)
+    for symbol_name, symbol_obj in imported_feature.symbols.items():
+        setattr(current_module, symbol_name, symbol_obj)
+        __all__ += [symbol_name]  # noqa: PLE0604

qilisdk/__init__.pyi

@@ -0,0 +1,30 @@
+# 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.analog import Hamiltonian
+from qilisdk.common import Algorithm, Model, Optimizer, Result
+from qilisdk.digital import DigitalSimulationMethod
+from qilisdk.extras.cuda import CudaBackend
+from qilisdk.extras.qaas.qaas_backend import QaaSBackend
+
+__all__ = [
+    "Algorithm",
+    "CudaBackend",
+    "DigitalSimulationMethod",
+    "Hamiltonian",
+    "Model",
+    "Optimizer",
+    "QaaSBackend",
+    "Result",
+]

qilisdk/_optionals.py

@@ -0,0 +1,105 @@
+# 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.
+
+import importlib
+import importlib.metadata
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+class OptionalDependencyError(ImportError):
+    """Raised when an optional dependency is missing, with a custom message."""
+
+
+@dataclass(frozen=True)
+class Symbol:
+    path: str
+    name: str
+
+
+@dataclass(frozen=True)
+class OptionalFeature:
+    """Holds metadata about an optional feature.
+
+    Attributes:
+        feature_name (str):
+            The name of the extras group in pyproject.toml
+        distributions (list[str]):
+            The PyPI distribution names that must be installed
+        import_path (str):
+            The Python import path to the module containing the real symbols
+        symbols (list[str]):
+            Which symbols (classes, functions, etc.) to re-export
+    """
+
+    name: str
+    dependencies: list[str]
+    symbols: list[Symbol]
+
+
+@dataclass
+class ImportedFeature:
+    """Holds the result of an optional import.
+
+    Attributes:
+        feature_name (str):
+            A label for the feature (e.g. 'qibo-backend').
+        symbol_map (dict[str, Union[Any, Callable]]):
+            A mapping from symbol name to the real or stubbed object.
+            If the required dependency is missing, the symbol is a stub
+            that raises an error when called.
+    """
+
+    name: str
+    symbols: dict[str, Any | Callable]
+
+
+def import_optional_dependencies(feature: OptionalFeature) -> ImportedFeature:
+    """Tries to import a submodule at `feature.import_path` along with the required
+    distributions. If successful, returns a dict mapping each symbol to the
+    actual imported symbol. Otherwise returns stubs that raise an error on usage.
+
+    Args:
+        feature (OptionalFeature): An OptionalFeature instance describing the optional group
+
+    Returns:
+        Dict[str, Union[Any, Callable]]: A dict { symbol_name: symbol_or_stub }
+    """
+    missing: list[str] = []
+    for dist in feature.dependencies:
+        try:
+            importlib.metadata.version(dist)
+        except importlib.metadata.PackageNotFoundError:
+            missing.append(dist)
+
+    if missing:
+        # Build stubs that raise a helpful error
+        def make_stub(symbol_name: str) -> Callable:
+            def _stub(*args: Any, **kwargs: Any) -> None:
+                raise OptionalDependencyError(
+                    f"Using {symbol_name} requires installing the '{feature.name}' optional feature: `pip install qilisdk[{feature.name}]`\n"
+                )
+
+            _stub.__name__ = symbol_name
+            return _stub
+
+        stubs = {symbol.name: make_stub(symbol.name) for symbol in feature.symbols}
+        return ImportedFeature(name=feature.name, symbols=stubs)
+
+    # All dependencies are present => import the real module
+    symbols = {}
+    for symbol in feature.symbols:
+        module = importlib.import_module(symbol.path)
+        symbols[symbol.name] = getattr(module, symbol.name)
+    return ImportedFeature(name=feature.name, symbols=symbols)

qilisdk/analog/__init__.py

@@ -0,0 +1,17 @@
+# 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 .hamiltonian import Hamiltonian, I, X, Y, Z
+
+__all__ = ["Hamiltonian", "I", "X", "Y", "Z"]

qilisdk/analog/algorithms.py

@@ -0,0 +1,111 @@
+# 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 abc import abstractmethod
+
+from qilisdk.analog.analog_backend import AnalogBackend
+from qilisdk.analog.analog_result import AnalogResult
+from qilisdk.analog.hamiltonian import Hamiltonian, PauliOperator
+from qilisdk.analog.quantum_objects import QuantumObject
+from qilisdk.analog.schedule import Schedule
+from qilisdk.common.algorithm import Algorithm
+from qilisdk.yaml import yaml
+
+Complex = int | float | complex
+
+
+@yaml.register_class
+class AnalogAlgorithm(Algorithm):
+    """
+    Abstract base class for analog quantum algorithms.
+
+    This class provides the foundational interface for analog quantum algorithms
+    that simulate the dynamics of quantum systems. It holds a reference to an
+    AnalogBackend instance responsible for executing quantum operations. Subclasses
+    must implement the evolve() method to perform the algorithm-specific simulation
+    and return an AnalogResult.
+
+    Attributes:
+        backend (AnalogBackend): The backend instance used to execute the quantum
+            simulation operations.
+    """
+
+    @abstractmethod
+    def evolve(self, backend: AnalogBackend, store_intermediate_results: bool = False) -> AnalogResult:
+        """
+        Execute the analog quantum algorithm's evolution process.
+
+        This abstract method defines the interface for simulating the time evolution
+        of a quantum system. Subclasses must implement this method to perform the
+        simulation using the provided backend, and to return the simulation results
+        encapsulated in an AnalogResult object.
+
+        Args:
+            store_intermediate_results (bool, optional): If True, the algorithm should
+                store and include intermediate results during the simulation. Defaults to False.
+
+        Returns:
+            AnalogResult: The result of the simulation, which includes the final state,
+            measured observables, and any intermediate data if requested.
+        """
+
+
+@yaml.register_class
+class TimeEvolution(AnalogAlgorithm):
+    def __init__(
+        self,
+        schedule: Schedule,
+        observables: list[PauliOperator | Hamiltonian],
+        initial_state: QuantumObject,
+        n_shots: int = 1000,
+    ) -> None:
+        """
+        Initialize the TimeEvolution simulation.
+
+        Args:
+            backend (AnalogBackend): The backend to use for simulating the dynamics.
+            schedule (Schedule): The evolution schedule defining the time-dependent Hamiltonian.
+            observables (list[PauliOperator | Hamiltonian]): A list of observables to measure at the end of the evolution.
+            initial_state (QuantumObject): The initial quantum state from which the simulation starts.
+            n_shots (int, optional): The number of simulation repetitions (shots). Defaults to 1000.
+        """
+        super().__init__()
+        self.initial_state = initial_state
+        self.schedule = schedule
+        self.observables = observables
+        self.n_shots = n_shots
+
+    def evolve(self, backend: AnalogBackend, store_intermediate_results: bool = False) -> AnalogResult:
+        """
+        Execute the time evolution algorithm.
+
+        This method performs the quantum dynamics evolution according to
+        the provided schedule, initial state, and observables. The computation
+        is delegated to the configured backend, which may optionally store
+        intermediate results during the evolution.
+
+        Args:
+            store_intermediate_results (bool, optional): If True, the algorithm
+                will store intermediate results during the time evolution.
+                Defaults to False.
+
+        Returns:
+            AnalogResult: The result of the evolution, including the final state
+            and measured observables (and intermediate results if requested).
+        """
+        return backend.evolve(
+            schedule=self.schedule,
+            initial_state=self.initial_state,
+            observables=self.observables,
+            store_intermediate_results=store_intermediate_results,
+        )

qilisdk/analog/analog_backend.py

@@ -0,0 +1,43 @@
+# 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 abc import abstractmethod
+
+from qilisdk.analog.analog_result import AnalogResult
+from qilisdk.analog.hamiltonian import Hamiltonian, PauliOperator
+from qilisdk.analog.quantum_objects import QuantumObject
+from qilisdk.analog.schedule import Schedule
+from qilisdk.common.backend import Backend
+
+
+class AnalogBackend(Backend):
+    @abstractmethod
+    def evolve(
+        self,
+        schedule: Schedule,
+        initial_state: QuantumObject,
+        observables: list[PauliOperator | Hamiltonian],
+        store_intermediate_results: bool = False,
+    ) -> AnalogResult:
+        """
+        Computes the time evolution under of an initial state under the given schedule.
+
+        Args:
+            schedule (Schedule): The evolution schedule of the system.
+            initial_state (QuantumObject): the initial state of the evolution.
+            observables (list[PauliOperator  |  Hamiltonian]): the list of observables to be measured at the end of the evolution.
+            store_intermediate_results (bool): A flag to store the intermediate results along the evolution.
+
+        Returns:
+            AnalogResult: The results of the evolution.
+        """

qilisdk/analog/analog_result.py

@@ -0,0 +1,114 @@
+# 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 pprint import pformat
+
+import numpy as np
+
+from qilisdk.analog.quantum_objects import QuantumObject
+from qilisdk.common import Result
+from qilisdk.yaml import yaml
+
+
+@yaml.register_class
+class AnalogResult(Result):
+    """
+    Encapsulates the outcome of an analog quantum simulation.
+
+    This result class stores key outputs from the simulation, including the
+    final expected measurement values, the complete time-evolution of expectation
+    values (if available), the final quantum state, and any intermediate quantum states.
+
+    Attributes:
+        _final_expected_values (np.ndarray): The final expectation values measured at the end of the simulation.
+        _expected_values (np.ndarray): The time-series of expectation values recorded during the simulation.
+        _final_state (QuantumObject | None): The final quantum state resulting from the simulation.
+        _intermediate_states (list[QuantumObject] | None): A list of intermediate quantum states obtained during evolution.
+    """
+
+    def __init__(
+        self,
+        final_expected_values: np.ndarray | None = None,
+        expected_values: np.ndarray | None = None,
+        final_state: QuantumObject | None = None,
+        intermediate_states: list[QuantumObject] | None = None,
+    ) -> None:
+        """
+        Initialize an AnalogResult instance with simulation outputs.
+
+        Args:
+            final_expected_values (np.ndarray | None, optional): An array of the final expectation
+                values measured at the end of the simulation. Defaults to an empty array if None.
+            expected_values (np.ndarray | None, optional): An array containing the evolution of
+                expectation values during the simulation. Defaults to an empty array if None.
+            final_state (QuantumObject | None, optional): The final quantum state as a QuantumObject.
+                Defaults to None.
+            intermediate_states (list[QuantumObject] | None, optional): A list of QuantumObjects representing
+                the intermediate states during the simulation. Defaults to None.
+        """
+        super().__init__()
+        self._final_expected_values = final_expected_values if final_expected_values is not None else np.array([])
+        self._expected_values = expected_values if expected_values is not None else np.array([])
+        self._final_state = final_state
+        self._intermediate_states = intermediate_states
+
+    @property
+    def final_expected_values(self) -> np.ndarray:
+        """
+        Get the final expectation values measured at the end of the simulation.
+
+        Returns:
+            np.ndarray: An array of the final expected values.
+        """
+        return self._final_expected_values
+
+    @property
+    def expected_values(self) -> np.ndarray:
+        """
+        Get the evolution of expectation values recorded during the simulation.
+
+        Returns:
+            np.ndarray: An array of expectation values over the course of the simulation.
+        """
+        return self._expected_values
+
+    @property
+    def final_state(self) -> QuantumObject | None:
+        """
+        Get the final quantum state produced by the simulation.
+
+        Returns:
+            QuantumObject | None: The final quantum state, or None if not available.
+        """
+        return self._final_state
+
+    @property
+    def intermediate_states(self) -> list[QuantumObject] | None:
+        """
+        Get the list of intermediate quantum states recorded during the simulation.
+
+        Returns:
+            list[QuantumObject] | None: A list of intermediate quantum states, or None if not stored.
+        """
+        return self._intermediate_states
+
+    def __repr__(self) -> str:
+        class_name = self.__class__.__name__
+        return (
+            f"{class_name}(\n"
+            f"  final_expected_values={pformat(self.final_expected_values)},\n"
+            f"  expected_values={pformat(self.expected_values)}\n"
+            f"  final_state={pformat(self.final_state)}\n"
+            f"  intermediate_states={pformat(self.intermediate_states)}\n"
+            ")"
+        )

qilisdk/analog/exceptions.py

@@ -0,0 +1,19 @@
+# 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.
+
+
+class InvalidHamiltonianOperation(Exception): ...
+
+
+class NotSupportedOperation(Exception): ...