qilisdk 0.1.8__cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl

qilisdk/optimizers/optimizer_result.py

@@ -0,0 +1,101 @@
+# 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 qilisdk.core.result import Result
+from qilisdk.yaml import yaml
+
+
+@yaml.register_class
+class OptimizerIntermediateResult(Result):
+    """
+    Represents an intermediate result.
+    """
+
+    def __init__(
+        self,
+        cost: float,
+        parameters: list[float],
+    ) -> None:
+        self._cost = cost
+        self._parameters = parameters
+
+    @property
+    def cost(self) -> float:
+        """Return the optimal cost value."""
+        return self._cost
+
+    @property
+    def parameters(self) -> list[float]:
+        """Return the optimal parameters as a list of floats."""
+        return list(self._parameters)
+
+    def __repr__(self) -> str:
+        """Return a formatted string representation for debugging."""
+        return f"OptimizerIntermediateResult(cost={self._cost}, parameters={self._parameters})"
+
+
+@yaml.register_class
+class OptimizerResult(Result):
+    """
+    Represents the result of an optimization run.
+    """
+
+    def __init__(
+        self,
+        optimal_cost: float,
+        optimal_parameters: list[float],
+        intermediate_results: list[OptimizerIntermediateResult] | None = None,
+    ) -> None:
+        """
+        Initialize an OptimizerResult.
+
+        Args:
+            optimal_cost (float): The optimal cost value.
+            optimal_parameters (List[float]): The parameters corresponding to the optimal cost.
+            intermediate_results (Optional[List[OptimizerResult]]): (Optional) A list of intermediate results recorded during optimization.
+                Each intermediate result is an OptimizerResult. Defaults to an empty list if not provided.
+        """
+        self._optimal_cost = optimal_cost
+        self._optimal_parameters = optimal_parameters
+        self._intermediate_results = intermediate_results or []
+
+    @property
+    def optimal_cost(self) -> float:
+        """Return the optimal cost value."""
+        return self._optimal_cost
+
+    @property
+    def optimal_parameters(self) -> list[float]:
+        """Return the optimal parameters as a list of floats."""
+        return list(self._optimal_parameters)
+
+    @property
+    def intermediate_results(self) -> list[OptimizerIntermediateResult]:
+        """
+        Return the list of intermediate results.
+
+        Each intermediate result is an instance of OptimizerResult containing:
+            - optimal_cost: The cost computed at that iteration.
+            - optimal_parameters: The parameters corresponding to that iteration.
+        """
+        return list(self._intermediate_results)
+
+    def __repr__(self) -> str:
+        """Return a formatted string representation for debugging."""
+        return (
+            f"OptimizerResult(optimal_cost={self._optimal_cost}, "
+            f"optimal_parameters={self._optimal_parameters}, "
+            f"intermediate_results={self._intermediate_results})"
+        )

qilisdk/optimizers/scipy_optimizer.py

@@ -0,0 +1,118 @@
+# 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 typing import TYPE_CHECKING, Any, Callable
+
+from scipy import optimize as scipy_optimize
+
+from qilisdk.yaml import yaml
+
+from .optimizer import Optimizer
+from .optimizer_result import OptimizerIntermediateResult, OptimizerResult
+
+if TYPE_CHECKING:
+    from scipy.optimize import OptimizeResult
+
+
+@yaml.register_class
+class SciPyOptimizer(Optimizer):
+    def __init__(
+        self,
+        method: str | Callable | None = None,
+        **kwargs: dict[str, Any],
+    ) -> None:
+        """Create a new Gradient Based optimizer instance.
+
+        Args:
+            method (str | Callable | None, optional):Type of solver.  Should be one of
+                    - 'Nelder-Mead
+                    - 'Powell'
+                    - 'CG'
+                    - 'BFGS'
+                    - 'Newton-CG'
+                    - 'L-BFGS-B'
+                    - 'TNC'
+                    - 'COBYLA'
+                    - 'COBYQA'
+                    - 'SLSQP'
+                    - 'trust-constr
+                    - 'dogleg'
+                    - 'trust-ncg'
+                    - 'trust-exact
+                    - 'trust-krylov
+                    - custom - a callable object, see `scipy.optimize.minimize <https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html>`__ for description.
+
+                    If not given, chosen to be one of ``BFGS``, ``L-BFGS-B``, ``SLSQP``,
+                    depending on whether or not the problem has constraints or bounds.
+            bounds (list[tuple[int, int]] | None, optional):
+                    Bounds on variables for Nelder-Mead, L-BFGS-B, TNC, SLSQP, Powell,
+                    trust-constr, COBYLA, and COBYQA methods. To specify it you can provide a sequence of ``(min, max)`` pairs
+                    for each element in parameter list.
+
+        Extra Args:
+            Any argument supported by `scipy.optimize.minimize <https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html>` can be passed.
+            Note: the parameters, cost function and the ``args`` that are passed to this function will be specified in the optimize method. Moreover, callbacks are not supported for the moment.
+        """
+        super().__init__()
+        self.method = method
+        self.extra_arguments = kwargs
+
+    def optimize(
+        self,
+        cost_function: Callable[[list[float]], float],
+        init_parameters: list[float],
+        bounds: list[tuple[float, float]],
+        store_intermediate_results: bool = False,
+    ) -> OptimizerResult:
+        """optimize the cost function and return the optimal parameters.
+
+        Args:
+            cost_function (Callable[[list[float]], float]): a function that takes in a list of parameters and returns the cost.
+            init_parameters (list[float]): the list of initial parameters. Note: the length of this list determines the number of parameters the optimizer will consider.
+            bounds (list[float, float]): a list of the variable value bounds.
+
+        Returns:
+            list[float]: the optimal set of parameters that minimize the cost function.
+        """
+        intermediate_results: list[OptimizerIntermediateResult] = []
+
+        def callback_fun(intermediate_result: OptimizeResult) -> None:
+            # Create an OptimizerResult for this intermediate iteration.
+            intermediate_results.append(
+                OptimizerIntermediateResult(cost=intermediate_result.fun, parameters=intermediate_result.x.tolist())
+            )
+
+        # Only pass the callback if we want to store intermediate results.
+        callback = callback_fun if store_intermediate_results else None
+
+        res = scipy_optimize.minimize(
+            cost_function,
+            x0=init_parameters,
+            method=self.method,
+            bounds=bounds,
+            jac=self.extra_arguments.get("jac", None),
+            hess=self.extra_arguments.get("hess", None),
+            hessp=self.extra_arguments.get("hessp", None),
+            constraints=self.extra_arguments.get("constraints", ()),
+            tol=self.extra_arguments.get("tol", None),
+            options=self.extra_arguments.get("options", None),
+            callback=callback,
+        )
+
+        return OptimizerResult(
+            optimal_cost=res.fun,
+            optimal_parameters=res.x.tolist(),
+            intermediate_results=intermediate_results,
+        )

qilisdk/settings.py

@@ -0,0 +1,103 @@
+# 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 enum import Enum
+from functools import lru_cache
+from pathlib import Path
+
+import numpy as np
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def default_logging_config_path() -> Path:
+    return Path(__file__).with_name("logging_config.yaml").resolve()
+
+
+class Precision(str, Enum):
+    COMPLEX_64 = "COMPLEX_64"
+    COMPLEX_128 = "COMPLEX_128"
+
+    @property
+    def dtype(self) -> np.dtype:
+        """
+        Resolve the numpy dtype associated with this complex precision.
+
+        Returns:
+            np.dtype: The corresponding numpy complex dtype.
+        """
+        match self:
+            case Precision.COMPLEX_64:
+                return np.complex64  # type: ignore[return-value]
+            case _:
+                return np.complex128  # type: ignore[return-value]
+
+
+class QiliSDKSettings(BaseSettings):
+    """
+    Environment-based configuration settings for QiliSDK.
+
+    These settings are automatically loaded from environment variables
+    prefixed with `QILISDK_`, or from a local `.env` file if present.
+    """
+
+    model_config = SettingsConfigDict(env_prefix="qilisdk_", env_file=".env", env_file_encoding="utf-8")
+
+    complex_precision: Precision = Field(default=Precision.COMPLEX_128, description="[env: QILISDK_COMPLEX_PRECISION]")
+    logging_config_path: Path = Field(
+        default_factory=default_logging_config_path,
+        description="YAML file used for logging configuration. [env: QILISDK_LOGGING_CONFIG_PATH]",
+    )
+    speqtrum_username: str | None = Field(
+        default=None,
+        description="SpeQtrum username used for authentication. [env: QILISDK_SPEQTRUM_USERNAME]",
+    )
+    speqtrum_apikey: str | None = Field(
+        default=None,
+        description="SpeQtrum API key associated with the user account. [env: QILISDK_SPEQTRUM_APIKEY]",
+    )
+    speqtrum_api_url: str = Field(
+        default="https://qilimanjaro.ddns.net/public-api/api/v1",
+        description="Base URL of the SpeQtrum API endpoint. [env: QILISDK_SPEQTRUM_API_URL]",
+    )
+    speqtrum_audience: str = Field(
+        default="urn:qilimanjaro.tech:public-api:beren",
+        description="Audience claim expected in the JWT used for authentication. [env: QILISDK_SPEQTRUM_AUDIENCE]",
+    )
+    atol: float = Field(
+        default=1e-10,
+        description="Numerical tolerance below which values are considered zero. [env: QILISDK_ATOL]",
+        gt=0.0,
+        lt=1.0,
+    )
+    rtol: float = Field(
+        default=1e-5,
+        description="Numerical relative tolerance below which values are considered zero. [env: QILISDK_RTOL]",
+        gt=0.0,
+        lt=1.0,
+    )
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> QiliSDKSettings:
+    """
+    Returns a singleton instance of QiliSDKSettings.
+
+    This function caches the parsed environment-based settings to avoid
+    redundant re-parsing across the application lifecycle.
+
+    Returns:
+        QiliSDKSettings: The cached configuration object populated from environment variables.
+    """
+    return QiliSDKSettings()

qilisdk/speqtrum/__init__.py

@@ -0,0 +1,41 @@
+# 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 qilisdk._optionals import ImportedFeature, OptionalFeature, Symbol, import_optional_dependencies
+
+__all__ = []
+
+OPTIONAL_FEATURES: list[OptionalFeature] = [
+    OptionalFeature(
+        name="speqtrum",
+        dependencies=["httpx", "keyring", "keyrings-alt"],
+        symbols=[
+            Symbol(path="qilisdk.speqtrum.speqtrum", name="SpeQtrum"),
+            Symbol(path="qilisdk.speqtrum.speqtrum_models", name="DeviceStatus"),
+            Symbol(path="qilisdk.speqtrum.speqtrum_models", name="DeviceType"),
+            Symbol(path="qilisdk.speqtrum.speqtrum_models", name="JobHandle"),
+            Symbol(path="qilisdk.speqtrum.speqtrum_models", name="TypedJobDetail"),
+        ],
+    ),
+]
+
+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/speqtrum/__init__.pyi

@@ -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 .speqtrum import SpeQtrum
+from .speqtrum_models import DeviceStatus, DeviceType
+
+__all__ = ["DeviceStatus", "DeviceType", "SpeQtrum"]

qilisdk/speqtrum/keyring.py

@@ -0,0 +1,58 @@
+# 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 keyring
+from keyring.errors import PasswordDeleteError
+from pydantic import ValidationError
+
+from .speqtrum_models import Token
+
+KEYRING_IDENTIFIER = "SpeQtrumKeyring"
+
+
+def store_credentials(username: str, token: Token) -> None:
+    """
+    Store the username and token in the keyring.
+    """
+    keyring.set_password(KEYRING_IDENTIFIER, "username", username)
+    keyring.set_password(KEYRING_IDENTIFIER, "token", token.model_dump_json())
+
+
+def delete_credentials() -> None:
+    """
+    Delete username and token from the keyring.
+    """
+    try:
+        keyring.delete_password(KEYRING_IDENTIFIER, "username")
+        keyring.delete_password(KEYRING_IDENTIFIER, "token")
+    except PasswordDeleteError:
+        return
+
+
+def load_credentials() -> tuple[str, Token] | None:
+    """
+    Attempt to load the stored username and token from the keyring.
+
+    Returns:
+        A tuple (username, Token) if both exist and can be parsed; otherwise, None.
+    """
+    username = keyring.get_password(KEYRING_IDENTIFIER, "username")
+    token_json = keyring.get_password(KEYRING_IDENTIFIER, "token")
+    if username is None or token_json is None:
+        return None
+    try:
+        token = Token.model_validate_json(token_json)
+        return username, token
+    except ValidationError:
+        return None