luna-quantum 1.0.0__cp313-cp313-manylinux_2_34_x86_64.whl

luna_quantum/solve/domain/solve_job.py

@@ -0,0 +1,187 @@
+from datetime import datetime
+from logging import Logger
+from typing import ClassVar, Literal
+
+from pydantic import BaseModel, PrivateAttr
+
+from luna_quantum._core import Solution
+from luna_quantum.aqm_overwrites.model import Model
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.client.schemas.enums.call_style import CallStyle
+from luna_quantum.client.schemas.enums.model_format import ModelFormat
+from luna_quantum.client.schemas.enums.status import StatusEnum
+from luna_quantum.factories.luna_solve_client_factory import LunaSolveClientFactory
+from luna_quantum.util.log_utils import Logging
+
+
+class SolveJob(BaseModel):
+    """A model to represent a job for solving model problems."""
+
+    _logger: ClassVar[Logger] = Logging.get_logger(__name__)
+    id: str
+    status: StatusEnum
+    status_timeline: dict[StatusEnum, datetime]
+    error_message: str | None = None
+    solver_job_info: str | None = None
+    used_format: ModelFormat | None = None
+    provider: str | None = None
+    is_cancelable: bool = True
+    is_cancellation_requested: bool = False
+
+    _result: Solution | None = PrivateAttr(default=None)
+
+    _model: Model | None = PrivateAttr(default=None)
+
+    def set_evaluation_model(self, model: Model | None) -> None:
+        """
+        Set the evaluation model for the solved job.
+
+        This will be done automatically. Normally there is no need to call this method.
+
+        Parameters
+        ----------
+        model: Model|None
+
+        """
+        self._model = model
+
+    def get_status(
+        self,
+        client: ILunaSolve | None = None,
+        status_source: Literal["cached", "remote"] = "cached",
+    ) -> StatusEnum:
+        """
+        Retrieve the current status of the solve job.
+
+        Parameters
+        ----------
+        status_source : Literal["cached", "remote"], optional
+            If "cached", the status is retrieved from the cached status. If "remote",
+            the status is retrieved from the remote service.
+
+        client : Optional[ILunaSolve], optional
+            The client to be used. If not provided, a new client is created using
+
+        Returns
+        -------
+        StatusEnum
+            The current status of the solve job, represented as a value
+            from the `StatusEnum` enumeration.
+
+        """
+        if status_source == "remote":
+            c: ILunaSolve = LunaSolveClientFactory.get_client(client)
+
+            from luna_quantum.factories.usecase_factory import UseCaseFactory
+
+            UseCaseFactory.solve_job_fetch_update(client=c).__call__(solve_job=self)
+
+        return self.status
+
+    def result(
+        self,
+        client: ILunaSolve | None = None,
+        sleep_time_max: float = 60.0,
+        sleep_time_increment: float = 5.0,
+        sleep_time_initial: float = 5.0,
+        call_style: CallStyle = CallStyle.ACTIVE_WAITING,
+    ) -> Solution | None:
+        """
+        Get the result of the solve job.
+
+        This function uses the provided client or creates a new one to retrieve
+        and the result of this solve job. Depending on the call style, it can
+        actively wait for the result or return immediately.
+
+        Parameters
+        ----------
+        client : Optional[ILunaSolve], optional
+            The client to be used. If not provided, a new client is created using
+            ClientFactory.
+        sleep_time_max : float, optional
+            Maximum sleep time in seconds between consecutive active waiting checks.
+        sleep_time_increment : float, optional
+            Increment value for the sleep time between checks during active waiting.
+        sleep_time_initial : float, optional
+            Initial sleep time in seconds for the active waiting process.
+        call_style : CallStyle, optional
+            Determines if this function will actively wait for the result or return
+            immediately.
+
+        Returns
+        -------
+        Optional[Solution]
+            The result of the solve job or None if not available.
+
+        Raises
+        ------
+        Any exceptions raised by the use case's solve job call will propagate.
+        """
+        if self._result:
+            return self._result
+
+        c: ILunaSolve = LunaSolveClientFactory.get_client(client)
+
+        from luna_quantum.factories.usecase_factory import UseCaseFactory
+
+        self._result = UseCaseFactory.solve_job_get_result(client=c).__call__(
+            solve_job=self,
+            sleep_time_max=sleep_time_max,
+            sleep_time_increment=sleep_time_increment,
+            sleep_time_initial=sleep_time_initial,
+            call_style=call_style,
+        )
+
+        if self._result is None:
+            return None
+        if self._model is None:
+            SolveJob._logger.info(
+                "The solve job object does not contain a model. "
+                "This solution is not evaluated."
+            )
+        else:
+            self._result = self._model.evaluate(self._result)
+
+        return self._result
+
+    def cancel(self, client: ILunaSolve | None = None) -> None:
+        """
+        Cancel a solve job.
+
+        This method cancels an already initiated solve job using the provided client
+        or a default one if no client is specified.
+
+        Parameters
+        ----------
+        client : Optional[ILunaSolve], optional
+            The client instance used to perform the cancel operation. If None, the
+            client is obtained via the ClientFactory.
+
+        Returns
+        -------
+        None
+        """
+        c: ILunaSolve = LunaSolveClientFactory.get_client(client)
+
+        from luna_quantum.factories.usecase_factory import UseCaseFactory
+
+        UseCaseFactory.solve_job_cancel(client=c).__call__(self)
+
+    def delete(self, client: ILunaSolve | None = None) -> None:
+        """
+        Delete a job using the specified or default client.
+
+        This method deletes this job and solution. A client can optionally be provided
+        otherwise, a default client is obtained through the factory.
+
+        Parameters
+        ----------
+        client : Optional[ILunaSolve], optional
+            The client to be used for job deletion. If not provided, a default client
+            is retrieved using `ClientFactory`.
+        """
+        c: ILunaSolve = LunaSolveClientFactory.get_client(client)
+
+        from luna_quantum.factories.usecase_factory import UseCaseFactory
+
+        UseCaseFactory.solve_job_delete(client=c).__call__(solve_job_id=self.id)

luna_quantum/solve/errors/incompatible_backend_error.py

@@ -0,0 +1,15 @@
+from luna_quantum.solve.errors.solve_base_error import SolveBaseError
+from luna_quantum.solve.interfaces.algorithm_i import BACKEND_TYPE, IAlgorithm
+from luna_quantum.solve.interfaces.backend_i import IBackend
+
+
+class IncompatibleBackendError(SolveBaseError):
+    """Exception raised if the backend is incompatible with the algorithm."""
+
+    def __init__(
+        self, backend: IBackend, algorithm: type[IAlgorithm[BACKEND_TYPE]]
+    ) -> None:
+        super().__init__(
+            f"Backend {backend.__class__.__name__} is incompatible "
+            f"with algorithm {algorithm.__name__}."
+        )

luna_quantum/solve/errors/model_metadata_missing_error.py

@@ -0,0 +1,11 @@
+from luna_quantum.solve.errors.solve_base_error import SolveBaseError
+
+
+class ModelMetadataMissingError(SolveBaseError):
+    """Exception raised for errors in the input."""
+
+    def __init__(self) -> None:
+        self.message = (
+            "Model metadata is required to complete this action. "
+            "Make sure that the model has been saved."
+        )

luna_quantum/solve/errors/solve_base_error.py

@@ -0,0 +1,5 @@
+from luna_quantum.exceptions.base_luna_quantum_error import BaseLunaQuantumError
+
+
+class SolveBaseError(BaseLunaQuantumError):
+    """Base class for all solve errors."""

luna_quantum/solve/errors/token_missing_error.py

@@ -0,0 +1,11 @@
+from luna_quantum.solve.errors.solve_base_error import SolveBaseError
+
+
+class TokenMissingError(SolveBaseError):
+    """Exception raised, when token is missing."""
+
+    def __init__(self) -> None:
+        self.message = (
+            "To complete this action, a token is required. "
+            "Make sure that the token has been set."
+        )

luna_quantum/solve/interfaces/algorithm_i.py

@@ -0,0 +1,47 @@
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+from luna_quantum.aqm_overwrites.model import Model
+from luna_quantum.solve.domain.solve_job import SolveJob
+from luna_quantum.solve.interfaces.backend_i import IBackend
+
+BACKEND_TYPE = TypeVar("BACKEND_TYPE", bound=IBackend)
+
+
+class IAlgorithm(ABC, Generic[BACKEND_TYPE]):
+    """
+    Interface for an algorithm that performs solve tasks based on a given model.
+
+    This interface defines the structure expected for any solver implementation
+    that can solve model problems and return results in the form of a `SolveJob`.
+    """
+
+    @abstractmethod
+    def run(
+        self,
+        model: Model | str,
+        name: str | None = None,
+        backend: BACKEND_TYPE | None = None,
+        *args: Any | None,
+        **kwargs: Any | None,
+    ) -> SolveJob:
+        """
+        Solve the given model problem and return the resulting job.
+
+        Parameters
+        ----------
+        model: Optimization
+            An instance of the `Optimization` class representing the problem
+            to be solved, including any constraints or objectives.
+        name: Optional[str]
+            If provided, the name of the job. Defaults to None.
+        backend: Optional[BACKEND_TYPE]
+            If provided, the backend to use for the solver. If no backend is provided,
+            the default backend for the solver will be used.
+
+        Returns
+        -------
+        SolveJob
+            A `SolveJob` object representing the results of the solve_job process,
+            including the solve_job state and related metadata.
+        """

luna_quantum/solve/interfaces/backend_i.py

@@ -0,0 +1,28 @@
+from abc import ABC, abstractmethod
+
+from pydantic import BaseModel, ConfigDict
+
+
+class IBackend(BaseModel, ABC):
+    """
+    Base interface for backend providers.
+
+    Defines an abstract interface for backend providers. This is used as a
+    base class for implementing and configuring specific backend providers.
+    """
+
+    @property
+    @abstractmethod
+    def provider(self) -> str:
+        """
+        Retrieve the name of the provider.
+
+        Returns
+        -------
+        str
+            The name of the provider.
+        """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )

luna_quantum/solve/interfaces/usecases/__init__.py

@@ -0,0 +1,55 @@
+from .model_delete_usecase_i import (
+    IModelDeleteUseCase,
+)
+from .model_fetch_metadata_usecase_i import (
+    IModelFetchMetadataUseCase,
+)
+from .model_get_solutions_usecase_i import (
+    IModelGetSolutionUseCase,
+)
+from .model_get_solve_jobs_usecase_i import (
+    IModelGetSolveJobUseCase,
+)
+from .model_load_by_id_usecase_i import (
+    IModelLoadByIdUseCase,
+)
+from .model_load_by_metadata_usecase_i import (
+    IModelLoadByMetadataUseCase,
+)
+from .model_load_metadata_by_hash_usecase_i import (
+    IModelLoadMetadataByHashUseCase,
+)
+from .model_save_usecase_i import (
+    IModelSaveUseCase,
+)
+from .solve_job_cancel_usecase_i import (
+    ISolveJobCancelUseCase,
+)
+from .solve_job_create_usecase_i import (
+    ISolveJobCreateUseCase,
+)
+from .solve_job_delete_usecase_i import (
+    ISolveJobDeleteUseCase,
+)
+from .solve_job_fetch_updates_usecase_i import (
+    ISolveJobFetchUpdatesUseCase,
+)
+from .solve_job_get_result_usecase_i import (
+    ISolveJobGetResultUseCase,
+)
+
+__all__ = [
+    "IModelDeleteUseCase",
+    "IModelFetchMetadataUseCase",
+    "IModelGetSolutionUseCase",
+    "IModelGetSolveJobUseCase",
+    "IModelLoadByIdUseCase",
+    "IModelLoadByMetadataUseCase",
+    "IModelLoadMetadataByHashUseCase",
+    "IModelSaveUseCase",
+    "ISolveJobCancelUseCase",
+    "ISolveJobCreateUseCase",
+    "ISolveJobDeleteUseCase",
+    "ISolveJobFetchUpdatesUseCase",
+    "ISolveJobGetResultUseCase",
+]

luna_quantum/solve/interfaces/usecases/model_delete_usecase_i.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luna_quantum.aqm_overwrites import Model
+    from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+
+
+class IModelDeleteUseCase(ABC):
+    """Interface for deleting a models."""
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, model: Model) -> None:
+        """
+        Abstract method for deleting a model.
+
+        Parameters
+        ----------
+        model : Model
+            Model to be deleted.
+        """

luna_quantum/solve/interfaces/usecases/model_fetch_metadata_usecase_i.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luna_quantum.aqm_overwrites import Model
+    from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+    from luna_quantum.solve.domain.model_metadata import ModelMetadata
+
+
+class IModelFetchMetadataUseCase(ABC):
+    """Abstract base class for fetching metadata of models."""
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, model: Model) -> ModelMetadata:
+        """
+        Abstract method for fetching metadata of an AQ model.
+
+        Parameters
+        ----------
+        model : Model
+            The model for which metadata is to be fetched.
+
+        Returns
+        -------
+        ModelMetadata
+            Metadata of the AQ model.
+        """

luna_quantum/solve/interfaces/usecases/model_get_solutions_usecase_i.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luna_quantum import Model, Solution
+    from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+
+
+class IModelGetSolutionUseCase(ABC):
+    """Interface to retrieve solutions for a specific Model."""
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, model: Model) -> list[Solution]:
+        """
+        Abstract method to retrieve solutions for a specific Model.
+
+        Parameters
+        ----------
+        model : Model
+            The model to be processed.
+
+        Returns
+        -------
+        list[Solution]
+            A list of solutions generated after processing the query model.
+
+        """

luna_quantum/solve/interfaces/usecases/model_get_solve_jobs_usecase_i.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luna_quantum.aqm_overwrites import Model
+    from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+    from luna_quantum.solve.domain.solve_job import SolveJob
+
+
+class IModelGetSolveJobUseCase(ABC):
+    """Interface for obtaining and solving Model jobs."""
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, model: Model) -> list[SolveJob]:
+        """
+        Abstract function to retrieve list of SolveJob objects from a given client.
+
+        Parameters
+        ----------
+        model : Model
+            The model for which SolveJob objects are to be retrieved.
+
+        Returns
+        -------
+        List[SolveJob]
+            A list of SolveJob objects.
+        """

luna_quantum/solve/interfaces/usecases/model_load_by_id_usecase_i.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luna_quantum.aqm_overwrites import Model
+    from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+
+
+class IModelLoadByIdUseCase(ABC):
+    """Interface for loading an AQ Model by its ID."""
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, model_id: str) -> Model:
+        """
+        Abstract method that retrieves a model instance by its identifier.
+
+        Parameters
+        ----------
+        model_id : str
+            A unique identifier of the model to be retrieved.
+
+        Returns
+        -------
+        Model
+            The model instance corresponding to the given identifier.
+        """

luna_quantum/solve/interfaces/usecases/model_load_by_metadata_usecase_i.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luna_quantum.aqm_overwrites import Model
+    from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+    from luna_quantum.solve.domain.model_metadata import ModelMetadata
+
+
+class IModelLoadByMetadataUseCase(ABC):
+    """Interface for loading an AQ model using metadata."""
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, model_metadata: ModelMetadata) -> Model:
+        """
+        Abstract method for loading the model by the metadata.
+
+        This method acts as an interface for running a specific AQ Model based on the
+        provided metadata and returning the constructed AQ model instance.
+
+        Parameters
+        ----------
+        model_metadata : ModelMetadata
+            Metadata required for constructing or running the AQ Model.
+
+        Returns
+        -------
+        Model
+            The constructed AQ Model instance.
+
+        """

luna_quantum/solve/interfaces/usecases/model_load_metadata_by_hash_usecase_i.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+    from luna_quantum.solve.domain.model_metadata import ModelMetadata
+
+
+class IModelLoadMetadataByHashUseCase(ABC):
+    """Interface for loading model metadata by hash."""
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, model_hash: int) -> ModelMetadata:
+        """
+        Abstract base class for callable objects that provide Model metadata.
+
+        This class defines a contract for objects that, when called, return
+        metadata associated with a particular Model specified by a unique
+        hash value.
+
+        Parameters
+        ----------
+        model_hash : int
+            A hash value uniquely identifying the Model for which metadata
+            is requested.
+
+        Returns
+        -------
+        ModelMetadata
+            Metadata associated with the specified Model.
+
+        """

luna_quantum/solve/interfaces/usecases/model_save_usecase_i.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luna_quantum.aqm_overwrites import Model
+    from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+    from luna_quantum.solve.domain.model_metadata import ModelMetadata
+
+
+class IModelSaveUseCase(ABC):
+    """Define an interface for handling Model saving use cases."""
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, model: Model) -> ModelMetadata:
+        """
+        Evaluate and retrieve metadata from an acquisition model.
+
+        This abstract method is intended to be implemented to process a given
+        acquisition model and derive specific metadata from it.
+
+        Parameters
+        ----------
+        model : Model
+            The acquisition model to be processed.
+
+        Returns
+        -------
+        ModelMetadata
+            The metadata derived from the acquisition model.
+        """

luna_quantum/solve/interfaces/usecases/solve_job_cancel_usecase_i.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+    from luna_quantum.solve.domain.solve_job import SolveJob
+
+
+class ISolveJobCancelUseCase(ABC):
+    """
+    Represent an abstract base for solving job cancellation use case.
+
+    This class defines the structure for a use case that allows canceling of solve
+    jobs. It acts as an interface specifying methods to be implemented by
+    concrete subclasses.
+    """
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, solve_job: SolveJob) -> None:
+        """
+        Represent an abstract base for callable objects handling solve jobs.
+
+        Parameters
+        ----------
+        solve_job : SolveJob
+            The input job to process or solve.
+        """