qilisdk 0.1.0__py3-none-any.whl

qilisdk/extras/qaas/keyring.py

@@ -0,0 +1,54 @@
+# 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 pydantic import ValidationError
+
+from .models import Token
+
+KEYRING_IDENTIFIER = "QaaSKeyring"
+
+
+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.
+    """
+    keyring.delete_password(KEYRING_IDENTIFIER, "username")
+    keyring.delete_password(KEYRING_IDENTIFIER, "token")
+
+
+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

qilisdk/extras/qaas/models.py

@@ -0,0 +1,57 @@
+# 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 pydantic import BaseModel, ConfigDict, Field
+
+
+class QaaSModel(BaseModel):
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
+class LoginPayload(BaseModel): ...
+
+
+class Token(QaaSModel):
+    """
+    Represents the structure of the login response:
+    {
+        "accessToken": "...",
+        "expiresIn": 123456789,
+        "issuedAt": "123456789",
+        "refreshToken": "...",
+        "tokenType": "bearer"
+    }
+    """
+
+    access_token: str = Field(alias="accessToken")
+    expires_in: int = Field(alias="expiresIn")
+    issued_at: str = Field(alias="issuedAt")
+    refresh_token: str = Field(alias="refreshToken")
+    token_type: str = Field(alias="tokenType")
+
+
+class DeviceStatus(str, Enum):
+    """Device status typing for posting"""
+
+    ONLINE = "online"
+    MAINTENANCE = "maintenance"
+    OFFLINE = "offline"
+
+
+class Device(QaaSModel):
+    id: int = Field(...)
+    name: str = Field(...)
+    status: DeviceStatus = Field(...)

qilisdk/extras/qaas/qaas_backend.py

@@ -0,0 +1,154 @@
+# 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
+
+import json
+import logging
+from base64 import urlsafe_b64encode
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+import httpx
+from pydantic import ValidationError
+
+from qilisdk.analog.analog_backend import AnalogBackend
+from qilisdk.digital.digital_backend import DigitalBackend
+
+from .keyring import delete_credentials, load_credentials, store_credentials
+from .models import Device, Token
+from .qaas_settings import QaaSSettings
+
+if TYPE_CHECKING:
+    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.digital.circuit import Circuit
+
+    from .qaas_digital_result import QaaSDigitalResult
+
+logging.basicConfig(
+    format="%(levelname)s [%(asctime)s] %(name)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S", level=logging.DEBUG
+)
+
+
+class QaaSBackend(DigitalBackend, AnalogBackend):
+    """
+    Manages communication with a hypothetical QaaS service via synchronous HTTP calls.
+
+    Credentials to log in can come from:
+      a) method parameters,
+      b) environment (via Pydantic),
+      c) keyring (fallback).
+    """
+
+    _api_url: str = "https://qilimanjaroqaas.ddns.net:8080/api/v1"
+    _authorization_request_url: str = "https://qilimanjaroqaas.ddns.net:8080/api/v1/authorisation-tokens"
+    _authorization_refresh_url: str = "https://qilimanjaroqaas.ddns.net:8080/api/v1/authorisation-tokens/refresh"
+
+    def __init__(self) -> None:
+        """
+        Normally, you won't call __init__() directly.
+        Instead, use QaaSBackend.login(...) to create a logged-in instance.
+        """  # noqa: DOC501
+        credentials = load_credentials()
+        if credentials is None:
+            raise RuntimeError(
+                "No valid QaaS credentials found in keyring."
+                "Please call QaaSBackend.login(username, apikey) or ensure environment variables are set."
+            )
+        self._username, self._token = credentials
+
+    @classmethod
+    def login(
+        cls,
+        username: str | None = None,
+        apikey: str | None = None,
+    ) -> bool:
+        # Use provided parameters or fall back to environment variables via Settings()
+        if not username or not apikey:
+            try:
+                # Load environment variables into the settings object.
+                settings = QaaSSettings()  # type: ignore[call-arg]
+                username = username or settings.username
+                apikey = apikey or settings.apikey
+            except ValidationError:
+                # Environment credentials could not be validated.
+                # Optionally, log error details here.
+                return False
+
+        if not username or not apikey:
+            # Insufficient credentials provided.
+            return False
+
+        # Send login request to QaaS
+        try:
+            assertion = {
+                "username": username,
+                "api_key": apikey,
+                "user_id": None,
+                "audience": QaaSBackend._api_url,
+                "iat": int(datetime.now(timezone.utc).timestamp()),
+            }
+            encoded_assertion = urlsafe_b64encode(json.dumps(assertion, indent=2).encode("utf-8")).decode("utf-8")
+            with httpx.Client(timeout=10.0) as client:
+                response = client.post(
+                    QaaSBackend._authorization_request_url,
+                    json={
+                        "grantType": "urn:ietf:params:oauth:grant-type:jwt-bearer",
+                        "assertion": encoded_assertion,
+                        "scope": "user profile",
+                    },
+                    headers={"X-Client-Version": "0.23.2"},
+                )
+                response.raise_for_status()
+                # Suppose QaaS returns {"token": "..."} in JSON
+                token = Token(**response.json())
+        except httpx.RequestError:
+            # Log error message
+            return False
+
+        store_credentials(username=username, token=token)
+        return True
+
+    @classmethod
+    def logout(cls) -> None:
+        delete_credentials()
+
+    def list_devices(self) -> list[Device]:
+        with httpx.Client(timeout=20.0) as client:
+            response = client.get(
+                QaaSBackend._api_url + "/devices",
+                headers={"X-Client-Version": "0.23.2", "Authorization": f"Bearer {self._token.access_token}"},
+            )
+            response.raise_for_status()
+            response_json = response.json()
+            devices = [Device(**item) for item in response_json["items"]]
+            return devices
+
+    def execute(self, circuit: Circuit, nshots: int = 1000) -> QaaSDigitalResult:
+        raise NotImplementedError
+
+    def evolve(
+        self,
+        schedule: Schedule,
+        initial_state: QuantumObject,
+        observables: list[PauliOperator | Hamiltonian],
+        store_intermediate_results: bool = False,
+    ) -> AnalogResult:
+        raise NotImplementedError
+
+    def run(self, algorithm: Algorithm) -> None:
+        raise NotImplementedError

qilisdk/extras/qaas/qaas_digital_result.py

@@ -0,0 +1,20 @@
+# 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.digital.digital_result import DigitalResult
+from qilisdk.yaml import yaml
+
+
+@yaml.register_class
+class QaaSDigitalResult(DigitalResult): ...

qilisdk/extras/qaas/qaas_settings.py

@@ -0,0 +1,23 @@
+# 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 pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class QaaSSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="qaas_", env_file=".env", env_file_encoding="utf-8")
+
+    username: str = Field(..., description="QaaS Username")
+    apikey: str = Field(..., description="QaaS API Key")

qilisdk/utils/__init__.py

@@ -0,0 +1,27 @@
+# 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 .openqasm2 import from_qasm2, from_qasm2_file, to_qasm2, to_qasm2_file
+from .serialization import deserialize, deserialize_from, serialize, serialize_to
+
+__all__ = [
+    "deserialize",
+    "deserialize_from",
+    "from_qasm2",
+    "from_qasm2_file",
+    "serialize",
+    "serialize_to",
+    "to_qasm2",
+    "to_qasm2_file",
+]

qilisdk/utils/openqasm2.py

@@ -0,0 +1,215 @@
+# 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 re
+from pathlib import Path
+
+from qilisdk.digital.circuit import Circuit
+from qilisdk.digital.exceptions import UnsupportedGateError
+from qilisdk.digital.gates import CNOT, CZ, RX, RY, RZ, U1, U2, U3, Gate, H, M, S, T, X, Y, Z
+
+OPENQASM2_MAP: dict[type[Gate], str] = {
+    X: "x",
+    Y: "y",
+    Z: "z",
+    H: "h",
+    S: "s",
+    T: "t",
+    RX: "rx",
+    RY: "ry",
+    RZ: "rz",
+    U1: "u1",
+    U2: "u2",
+    U3: "u3",
+    CNOT: "cx",
+    CZ: "cz",
+}
+
+
+def to_qasm2(circuit: Circuit) -> str:
+    """
+    Convert the circuit to an OpenQASM 2.0 formatted string.
+
+    Args:
+        circuit: The circuit to convert to OpenQASM 2.0.
+
+    Returns:
+        str: The OpenQASM 2.0 representation of the circuit.
+    """
+    qasm_lines: list[str] = []
+    # QASM header, standard library and quantum register.
+    qasm_lines.extend(("OPENQASM 2.0;", 'include "qelib1.inc";', f"qreg q[{circuit.nqubits}];"))
+
+    # If any measurement is present, declare a classical register.
+    if any(isinstance(gate, M) for gate in circuit.gates):
+        qasm_lines.append(f"creg c[{circuit.nqubits}];")
+
+    # Process each gate.
+    for gate in circuit.gates:
+        # Special conversion for measurement.
+        if isinstance(gate, M):
+            if len(gate.target_qubits) == circuit.nqubits:
+                qasm_lines.append("measure q -> c;")
+            else:
+                # Generate a measurement for each target qubit.
+                measurements = (f"measure q[{q}] -> c[{q}];" for q in gate.target_qubits)
+                qasm_lines.extend(measurements)
+        else:
+            # Map the internal gate name to its QASM equivalent.
+            qasm_name = OPENQASM2_MAP.get(type(gate), gate.name.lower())
+            # Format parameter string, if any.
+            param_str = ""
+            if gate.is_parameterized:
+                parameters = ", ".join(str(p) for p in gate.parameter_values)
+                param_str = f"({parameters})"
+            # Format qubit operands.
+            qubit_str = ", ".join(f"q[{q}]" for q in gate.qubits)
+            qasm_lines.append(f"{qasm_name}{param_str} {qubit_str};")
+
+    return "\n".join(qasm_lines)
+
+
+def to_qasm2_file(circuit: Circuit, filename: str) -> None:
+    """
+    Save the QASM representation to a file.
+
+    Args:
+        circuit: The circuit to convert to OpenQASM 2.0.
+        filename (str): The path to the file where the QASM code will be saved.
+    """
+    qasm_code = to_qasm2(circuit)
+    Path(filename).write_text(qasm_code, encoding="utf-8")
+
+
+# TODO(vyron): Add full support for OpenQASM 2.0 grammar.
+def from_qasm2(qasm_str: str) -> Circuit:
+    """
+    Parse an OpenQASM 2.0 string and create a corresponding Circuit instance.
+
+    This parser supports the following instructions:
+        - Quantum register declaration (e.g., "qreg q[3];")
+        - Classical register declaration (ignored)
+        - Gate instructions (one-qubit and two-qubit gates)
+        - Measurement instructions (e.g., "measure q[0] -> c[0];")
+
+    Args:
+        qasm_str (str): The QASM string to parse.
+
+    Returns:
+        Circuit: The constructed Circuit object.
+    """  # noqa: DOC501
+    # Mapping from QASM gate names (lowercase) to internal gate names.
+    reverse_qasm2_map = {v: k for k, v in OPENQASM2_MAP.items()}
+
+    circuit = None
+    lines = qasm_str.splitlines()
+    for raw_line in lines:
+        line = raw_line.strip()
+        if not line or line.startswith("//"):
+            continue
+        # Skip header and include lines.
+        if line.startswith(("OPENQASM", "include")):
+            continue
+        # Parse quantum register declaration.
+        if line.startswith("qreg"):
+            # e.g., "qreg q[3];"
+            m = re.match(r"qreg\s+\w+\[(\d+)\];", line)
+            if m:
+                nqubits = int(m.group(1))
+                circuit = Circuit(nqubits)
+            continue
+        # Skip classical register declaration.
+        if line.startswith("creg"):
+            continue
+        # Process measurement instructions.
+        if line.startswith("measure"):
+            # e.g., "measure q[0] -> c[0];"
+            m = re.match(r"measure\s+q\[(\d+)\]\s*->\s*c\[\d+\];", line)
+            if m:
+                # TODO(vyron): Check consecutive lines of measurement and combine into single M.
+                q_index = int(m.group(1))
+                if circuit is None:
+                    raise ValueError("Quantum register must be declared before measurement.")
+                circuit.add(M(q_index))
+            else:
+                # Special case: "measure q -> c;" means measure all qubits
+                m_all = re.match(r"measure\s+q\s*->\s*c\s*;", line)
+                if m_all:
+                    if circuit is None:
+                        raise ValueError("Quantum register must be declared before measurement.")
+                    circuit.add(M(*list(range(circuit.nqubits))))
+            continue
+        # Process gate instructions.
+        # Pattern breakdown:
+        #   Group 1: gate name (e.g., "h", "rx", "cx")
+        #   Group 2: optional parameters (inside parentheses)
+        #   Group 3: operand list (e.g., "q[0]" or "q[0], q[1]")
+        m = re.match(r"^(\w+)(?:\(([^)]*)\))?\s+(.+);$", line)
+        if m:
+            qasm_gate_name = m.group(1)
+            params_str = m.group(2)
+            operands_str = m.group(3)
+
+            # Convert QASM gate name to internal gate name.
+            gate_class = reverse_qasm2_map.get(qasm_gate_name.lower())
+            if gate_class is None:
+                raise UnsupportedGateError(f"Unknown gate: {qasm_gate_name}")
+
+            # Extract qubit indices.
+            qubit_matches = re.findall(r"q\[(\d+)\]", operands_str)
+            qubits = [int(q) for q in qubit_matches]
+
+            # Parse parameters, if any.
+            parameters = []
+            if params_str:
+                parameters = [float(p.strip()) for p in params_str.split(",") if p.strip()]
+
+            # Instantiate the gate based on the number of qubits.
+            # For one-qubit gates.
+            if len(qubits) == 1:
+                if gate_class.PARAMETER_NAMES:
+                    # Build a dictionary of parameter names to values.
+                    param_dict = {name: parameters[i] for i, name in enumerate(gate_class.PARAMETER_NAMES)}
+                    gate_instance = gate_class(qubits[0], **param_dict)  # type: ignore[call-arg]
+                else:
+                    gate_instance = gate_class(qubits[0])  # type: ignore[call-arg]
+            # For two-qubit gates.
+            elif len(qubits) == 2:  # noqa: PLR2004
+                if gate_class.PARAMETER_NAMES:
+                    param_dict = {name: parameters[i] for i, name in enumerate(gate_class.PARAMETER_NAMES)}
+                    gate_instance = gate_class(qubits[0], qubits[1], **param_dict)  # type: ignore[call-arg]
+                else:
+                    gate_instance = gate_class(qubits[0], qubits[1])  # type: ignore[call-arg]
+            else:
+                raise UnsupportedGateError("Only one- and two-qubit gates are supported.")
+
+            if circuit is None:
+                raise ValueError("Quantum register must be declared before adding gates.")
+            circuit.add(gate_instance)
+    if circuit is None:
+        raise ValueError("No quantum register declaration found in QASM.")
+    return circuit
+
+
+def from_qasm2_file(filename: str) -> Circuit:
+    """
+    Read an OpenQASM 2.0 file and create a corresponding Circuit instance.
+
+    Args:
+        filename (str): The path to the QASM file.
+
+    Returns:
+        Circuit: The reconstructed Circuit object.
+    """
+    qasm_str = Path(filename).read_text(encoding="utf-8")
+    return from_qasm2(qasm_str)

qilisdk/utils/serialization.py

@@ -0,0 +1,128 @@
+# Copyright 2023 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.
+
+# ruff: noqa: ANN401
+
+from io import StringIO
+from pathlib import Path
+from typing import Any, TypeVar, overload
+
+from qilisdk.yaml import yaml
+
+T = TypeVar("T")
+
+
+class SerializationError(Exception):
+    """Custom exception for serialization errors."""
+
+
+class DeserializationError(Exception):
+    """Custom exception for deserialization errors."""
+
+
+def serialize(obj: Any) -> str:
+    """Serialize an object to a YAML string.
+
+    Args:
+        obj (Any): The object to serialize.
+
+    Raises:
+        SerializationError: If serialization fails.
+
+    Returns:
+        str: The serialized YAML string.
+    """
+    try:
+        with StringIO() as stream:
+            yaml.dump(obj, stream)
+            return stream.getvalue()
+    except Exception as e:
+        raise SerializationError(f"Failed to serialize object {e}") from e
+
+
+def serialize_to(obj: Any, file: str) -> None:
+    """Serialize an object to a YAML file.
+
+    Args:
+        obj (Any): The object to serialize.
+        file (str): The file path where the YAML data will be written.
+
+    Raises:
+        SerializationError: If serialization to file fails.
+    """
+    try:
+        yaml.dump(obj, Path(file))
+    except Exception as e:
+        raise SerializationError(f"Failed to serialize object {e} to file {file}") from e
+
+
+@overload
+def deserialize(string: str) -> Any: ...
+
+
+@overload
+def deserialize(string: str, cls: type[T]) -> T: ...
+
+
+def deserialize(string: str, cls: type[T] | None = None) -> Any | T:
+    """Deserialize a YAML string to an object.
+
+    Args:
+        string (str): The YAML string to deserialize.
+        cls (type[T], optional): The class type to cast the deserialized object to. Defaults to None.
+
+    Raises:
+        DeserializationError: If deserialization fails or the resulting object is not of the specified type.
+
+    Returns:
+        Any | T: The deserialized object, optionally cast to the specified class type.
+    """
+    try:
+        with StringIO(string) as stream:
+            result = yaml.load(stream)
+    except Exception as e:
+        raise DeserializationError(f"Failed to deserialize YAML string: {e}") from e
+    if cls is not None and not isinstance(result, cls):
+        raise DeserializationError(f"Deserialized object is not of type {cls.__name__}")
+    return result
+
+
+@overload
+def deserialize_from(file: str) -> Any: ...
+
+
+@overload
+def deserialize_from(file: str, cls: type[T]) -> T: ...
+
+
+def deserialize_from(file: str, cls: type[T] | None = None) -> Any | T:
+    """Deserialize a YAML file to an object.
+
+    Args:
+        file (str): The file path of the YAML file to deserialize.
+        cls (type[T], optional): The class type to cast the deserialized object to. Defaults to None.
+
+    Raises:
+        DeserializationError: If deserialization fails or the resulting object is not of the specified type.
+
+    Returns:
+        Any | T: The deserialized object, optionally cast to the specified class type.
+    """
+    try:
+        result = yaml.load(Path(file))
+    except Exception as e:
+        raise DeserializationError(f"Failed to deserialize YAML string {e} from file {file}") from e
+    if cls is not None and not isinstance(result, cls):
+        raise DeserializationError(f"Deserialized object is not of type {cls.__name__}")
+    return result