luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

luna_quantum/solve/usecases/solve_job_get_result_usecase.py

@@ -0,0 +1,105 @@
+from luna_quantum._core import Solution
+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.status import StatusEnum
+from luna_quantum.exceptions.luna_quantum_call_type_error import (
+    LunaQuantumCallStyleError,
+)
+from luna_quantum.solve.domain.solve_job import SolveJob
+from luna_quantum.solve.interfaces.usecases.solve_job_get_result_usecase_i import (
+    ISolveJobGetResultUseCase,
+)
+from luna_quantum.util.active_waiting import ActiveWaiting
+from luna_quantum.util.log_utils import Logging, progress
+
+
+class SolveJobGetResultUseCase(ISolveJobGetResultUseCase):
+    """
+    Handle the process of retrieving and interacting with a solve job's result.
+
+    This class interacts with a backend client to manage fetching and handling
+    results for a solve job, using different strategies for waiting and polling
+    depending on the specified call style.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        Client used to interact with the solve job and retrieve its results.
+    """
+
+    client: ILunaSolve
+    logger = Logging.get_logger(__name__)
+
+    def __init__(self, client: ILunaSolve) -> None:
+        self.client = client
+
+    @progress(total=None, desc="Retrieving solve job...")
+    def __call__(
+        self,
+        solve_job: SolveJob,
+        sleep_time_max: float,
+        sleep_time_increment: float,
+        sleep_time_initial: float,
+        call_style: CallStyle,
+    ) -> Solution | None:
+        """
+        Execute the given solve job with specified waiting strategy.
+
+        Parameters
+        ----------
+        solve_job : SolveJob
+            The job that needs to be solved.
+        sleep_time_max : float
+            The maximum amount of time to wait between checks.
+        sleep_time_increment : float
+            The incremental step to increase sleep time during active waiting.
+        sleep_time_initial : float
+            The initial sleep time for the waiting strategy.
+        call_style : CallStyle
+            The style of waiting (e.g., active waiting) to use when processing the job.
+
+        Returns
+        -------
+        Optional[Solution]
+            The solution for the given solve job if successfully processed, otherwise
+            None.
+        """
+        match call_style:
+            case CallStyle.ACTIVE_WAITING:
+                final_states = StatusEnum.CANCELED, StatusEnum.DONE, StatusEnum.FAILED
+
+                ActiveWaiting.run(
+                    loop_check=lambda: solve_job.get_status(
+                        client=self.client, status_source="remote"
+                    )
+                    not in final_states,
+                    loop_call=None,
+                    sleep_time_max=sleep_time_max,
+                    sleep_time_increment=sleep_time_increment,
+                    sleep_time_initial=sleep_time_initial,
+                )
+            case CallStyle.SINGLE_FETCH:
+                solve_job.get_status(client=self.client, status_source="remote")
+
+            case _:
+                raise LunaQuantumCallStyleError(call_style)
+
+        try:
+            if solve_job.status == StatusEnum.CANCELED:
+                self.logger.warning(
+                    "Solve job is cancelled. Result cannot be retrieved."
+                )
+                return None
+            if solve_job.status == StatusEnum.FAILED:
+                self.logger.error(
+                    f"Solve job failed with the error '{solve_job.error_message}'."
+                )
+                return None
+            aq_solution: Solution = self.client.solve_job.get_solution(
+                solve_job_id=solve_job.id
+            )
+        except Exception:
+            # TODO(Llewellyn) more fine grained exception handling # noqa: FIX002, TD004
+            return None
+
+        return aq_solution

luna_quantum/transformations.py

@@ -0,0 +1,18 @@
+"""Transformations collection.
+
+The `transformations` module provides a collection of transformations for converting
+between various representations of optimization problems and their solutions.
+
+Transformations generally convert between different representations of an optimization
+model. For example, changing the Sense of a model.
+
+Each transformation encapsulates the logic needed for transforming a model to a desired
+output model with changed properties and the logic to convert a solution of the output
+model back to a solution representation matching the input model.
+
+In addition to the predefined transformations contained in this module.
+One can implement their own transformations by implementing the `TransformationPass`
+and `AnalysisPass` abstract classes. See the examples for further details.
+"""
+
+from ._core.transformations import *  # type: ignore[reportMissingImports] # noqa: F403

luna_quantum/transformations.pyi

@@ -0,0 +1,371 @@
+from abc import abstractmethod
+from collections.abc import Callable
+from enum import Enum
+from typing import Any, Literal, overload
+
+from . import Model, Sense, Solution, Timing, Vtype
+
+class BasePass:
+    @property
+    def name(self) -> str:
+        """Get the name of this pass."""
+        ...
+    @property
+    def requires(self) -> list[str]:
+        """Get a list of required passes that need to be run before this pass."""
+        ...
+
+class Pipeline(BasePass):
+    @overload
+    def __init__(self, passes: list[BasePass]) -> None: ...
+    @overload
+    def __init__(self, passes: list[BasePass], name: str) -> None: ...
+    def __init__(self, passes: list[BasePass], name: str | None = ...) -> None: ...
+    @property
+    def name(self) -> str:
+        """Get the name of this pass."""
+        ...
+    @property
+    def requires(self) -> list[str]:
+        """Get a list of required passes that need to be run before this pass."""
+        ...
+
+    @property
+    def satisfies(self) -> set[str]:
+        """Get a list of required passes that need to be run before this pass."""
+        ...
+
+    def add(self, new_pass: BasePass) -> None:
+        """Add new pass to pipeline."""
+        ...
+
+    def clear(self) -> None:
+        """Clear pipeline."""
+        ...
+
+    @property
+    def passes(self) -> list[BasePass]:
+        """Get all passes that are part of the pipeline."""
+        ...
+
+    def __len__(self) -> int: ...
+
+class IfElsePass(BasePass):
+    @overload
+    def __init__(
+        self,
+        requires: list[str],
+        condition: Callable[[AnalysisCache], bool],
+        then: Pipeline,
+        otherwise: Pipeline,
+    ) -> None: ...
+    @overload
+    def __init__(
+        self,
+        requires: list[str],
+        condition: Callable[[AnalysisCache], bool],
+        then: Pipeline,
+        otherwise: Pipeline,
+        name: str,
+    ) -> None: ...
+    def __init__(
+        self,
+        requires: list[str],
+        condition: Callable[[AnalysisCache], bool],
+        then: Pipeline,
+        otherwise: Pipeline,
+        name: str | None = ...,
+    ) -> None: ...
+    @property
+    def name(self) -> str:
+        """Get the name of this pass."""
+        ...
+    @property
+    def requires(self) -> list[str]:
+        """Get a list of required passes that need to be run before this pass."""
+        ...
+
+class TransformationPass(BasePass):
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Get the name of this pass."""
+        ...
+    @property
+    def requires(self) -> list[str]:
+        """Get a list of required passes that need to be run before this pass."""
+        ...
+    @property
+    def invalidates(self) -> list[str]:
+        """Get a list of passes that are invalidated by this pass."""
+        ...
+    @abstractmethod
+    def run(
+        self, model: Model, cache: AnalysisCache
+    ) -> (
+        TransformationOutcome | tuple[Model, ActionType] | tuple[Model, ActionType, Any]
+    ):
+        """Run/Execute this transformation pass."""
+        ...
+    @abstractmethod
+    def backwards(self, solution: Solution, cache: AnalysisCache) -> Solution:
+        """Convert a solution back to fit this pass' input.
+
+        Convert a solution from a representation fitting this pass' output to
+        a solution representation fitting this pass' input.
+        """
+        ...
+
+class TransformationOutcome:
+    """Output object for transformation pass."""
+
+    model: Model
+    action: ActionType
+    analysis: ...
+
+    @overload
+    def __init__(self, model: Model, action: ActionType) -> None: ...
+    @overload
+    def __init__(self, model: Model, action: ActionType, analysis: object) -> None: ...
+    def __init__(
+        self, model: Model, action: ActionType, analysis: object | None = ...
+    ) -> None: ...
+    @staticmethod
+    def nothing(model: Model) -> TransformationOutcome:
+        """Easy nothing action return."""
+        ...
+
+class AnalysisCache:
+    @overload
+    def __getitem__(  # type: ignore[reportOverlappingOverload]
+        self, key: Literal["max-bias"]
+    ) -> MaxBias: ...
+    @overload
+    def __getitem__(self, key: str) -> ...: ...
+    def __getitem__(self, key: str) -> Any:
+        """Get the analysis result for a specific analysis pass."""
+        ...
+
+class AnalysisPass(BasePass):
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Get the name of this pass."""
+        ...
+    @property
+    def requires(self) -> list[str]:
+        """Get a list of required passes that need to be run before this pass."""
+        ...
+    @abstractmethod
+    def run(self, model: Model, cache: AnalysisCache) -> ...:
+        """Run/Execute this analysis pass."""
+        ...
+
+class MetaAnalysisPass(BasePass):
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Get the name of this pass."""
+        ...
+    @property
+    def requires(self) -> list[str]:
+        """Get a list of required passes that need to be run before this pass."""
+        ...
+    @abstractmethod
+    def run(self, passes: list[BasePass], cache: AnalysisCache) -> ...:
+        """Run/Execute this analysis pass."""
+        ...
+
+class ActionType(Enum):
+    DidTransform = ...
+    """Indicate that the pass did transform the model."""
+    DidAnalysis = ...
+    """Indicate that the pass did analyse the model."""
+    DidAnalysisTransform = ...
+    """Indicate that the pass did analyse and transfrom the model."""
+    DidNothing = ...
+    """Indicate that the pass did NOT do anything."""
+
+class ChangeSensePass(BasePass):
+    """A transformation pass to change the model's Sense to a target Sense."""
+
+    def __init__(self, sense: Sense) -> None:
+        """Transform the model's Sense to a target Sense.
+
+        Parameters
+        ----------
+        sense : Sense
+            The target sense of the model after calling the `run` method on it.
+        """
+        ...
+    @property
+    def sense(self) -> Sense:
+        """Get the specified target sense of this pass."""
+        ...
+
+class MaxBias:
+    """An analysis pass result storing the max bias (coefficient) of a model."""
+
+    @property
+    def val(self) -> float:
+        """Get the value of the maxium bias."""
+        ...
+
+class MaxBiasAnalysis(BasePass):
+    """An analysis pass computing the maximum bias contained in the model."""
+
+    def __init__(self) -> None: ...
+
+class BinarySpinPass(BasePass):
+    """An transformation pass changing the binary/spin variables to spin/binary."""
+
+    def __init__(
+        self, vtype: Literal[Vtype.Binary, Vtype.Spin], prefix: str | None
+    ) -> None: ...
+    @property
+    def vtype(self) -> Vtype:
+        """Get the target vtype."""
+        ...
+
+    @property
+    def prefix(self) -> str | None:
+        """Get the naming prefix."""
+        ...
+
+class BinarySpinInfo:
+    @property
+    def old_vtype(self) -> Vtype:
+        """Get the source vtype."""
+        ...
+
+    @property
+    def new_vtype(self) -> Vtype:
+        """Get the variable name mapping."""
+        ...
+
+class LogElement:
+    """An element of the execution log of an intermediate representation (IR)."""
+
+    @property
+    def pass_name(self) -> str:
+        """The name of the pass."""
+        ...
+
+    @property
+    def timing(self) -> Timing:
+        """Timing information for this log element."""
+        ...
+
+    @property
+    def kind(self) -> ActionType | None:
+        """Transformation type information for this log element, if available."""
+        ...
+
+    # @property
+    # def components(self) -> list[LogElement] | None:
+    #     """Components of this log-element."""
+    #     ...
+
+class IR:
+    """The intermediate representation (IR) of a model after transformation.
+
+    The IR contains the resulting model after transformation (`ir.model`) as well
+    as the analysis cache (`ir.cache`) and an execution log (`ir.execution_log`).
+    """
+
+    @property
+    def model(self) -> Model:
+        """Get the model stored in the IR."""
+        ...
+
+    @property
+    def cache(self) -> AnalysisCache:
+        """Get the analysis cache stored the IR."""
+        ...
+
+    @property
+    def execution_log(self) -> list[LogElement]:
+        """Get the analysis cache stored the IR."""
+        ...
+
+class PassManager:
+    """Manage and execute a sequence of passes on a model.
+
+    The PassManager implements a compiler-style pass pattern, enabling both
+    general-purpose and algorithm-specific manipulations of optimization
+    models. Each pass is an atomic operation (for example, ChangeSensePass)
+    that transforms the model or its intermediate representation (IR). The
+    PassManager runs each pass in order and produces a rich IR that records
+    the transformations applied and supports back-transformations.
+    """
+
+    def __init__(
+        self, passes: list[BasePass | TransformationPass | AnalysisPass] | None = ...
+    ) -> None:
+        """Manage and execute a sequence of passes on a model.
+
+        The PassManager implements a compiler-style pass pattern, enabling both
+        general-purpose and algorithm-specific manipulations of optimization
+        models. Each pass is an atomic operation (for example, ChangeSensePass)
+        that transforms the model or its intermediate representation (IR). The
+        PassManager runs each pass in order and produces a rich IR that records
+        the transformations applied and supports back-transformations.
+
+        Parameters
+        ----------
+        passes : list[TransformationPass | AnalysisPass] | None
+            An ordered sequence of Pass instances to apply. Each Pass must conform to
+            the `TransformationPass` or `AnalysisPass` interface, default None.
+        """
+        ...
+
+    def run(self, model: Model) -> IR:
+        """Apply all configures passes.
+
+        Apply all configured passes to the given model and return the
+        resulting intermediate representation.
+
+        Parameters
+        ----------
+        model : Model
+            The model to be transformed.
+
+        Returns
+        -------
+        IR
+            The intermediate representation of the model after transformation.
+        """
+        ...
+
+    def backwards(self, solution: Solution, ir: IR) -> Solution:
+        """Apply the back transformation to the given solution.
+
+        Parameters
+        ----------
+        solution : Solution
+            The solution to transform back to a representation fitting the original
+            (input) model of this `PassManager`.
+        ir : IR
+            The intermediate representation (IR) resulted from the `run` call.
+
+        Returns
+        -------
+        Solution
+            A solution object representing a solution to the original problem passed
+            to this `PassManager`'s run method.
+        """
+        ...
+
+__all__ = [
+    "IR",
+    "ActionType",
+    "AnalysisCache",
+    "AnalysisPass",
+    "BasePass",
+    "ChangeSensePass",
+    "LogElement",
+    "MaxBias",
+    "MaxBiasAnalysis",
+    "PassManager",
+    "TransformationPass",
+]

luna_quantum/translator.py

@@ -0,0 +1,23 @@
+"""Translator collection.
+
+The `translator` module provides a collection of translators for converting between
+various formats related to optimization problems and their solutions.
+
+Translators are categorized into two main groups:
+
+1. **Model Translators**: These handle conversions *to* and *from* the internal `Model`
+   representation. They enable interoperability between external formats
+   (e.g., QUBO, LP) and the standardized internal model format used within the system.
+
+2. **Solution Translators**: These support conversion *from* external solution formats
+   into the internal `Solution` representation. This enables solutions generated by
+   different solvers or formats to be interpreted and processed consistently within
+   the system. Note that these translators do not support conversion *from* the internal
+   solution to external formats.
+
+Each translator encapsulates the logic needed for bidirectional format conversion,
+ensuring consistency and modularity when integrating with diverse optimization
+frameworks and solvers.
+"""
+
+from ._core.translator import *  # type: ignore[reportMissingImports] # noqa: F403