luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

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.
+        """

luna_quantum/solve/interfaces/usecases/solve_job_create_usecase_i.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luna_quantum.aqm_overwrites.model import Model
+    from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+    from luna_quantum.solve.domain.abstract import LunaAlgorithm
+    from luna_quantum.solve.domain.solve_job import SolveJob
+    from luna_quantum.solve.interfaces.algorithm_i import BACKEND_TYPE
+
+
+class ISolveJobCreateUseCase(ABC):
+    """
+    Abstract base class for a Solve Job Create use case.
+
+    Defines the abstract methods to initialize the use case with a client and
+    handle the execution of the use case, which involves processing a model.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        Instance of the solving client.
+    """
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(
+        self,
+        model: Model | str,
+        luna_solver: LunaAlgorithm[BACKEND_TYPE],
+        backend: BACKEND_TYPE,
+        name: str | None,
+    ) -> SolveJob:
+        """
+        Abstract base class for objects that are callable and return a Model.
+
+        Classes implementing this interface are designed to be called with a
+        Model instance and return a Model.
+        """

luna_quantum/solve/interfaces/usecases/solve_job_delete_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.client.interfaces.services.luna_solve_i import ILunaSolve
+
+
+class ISolveJobDeleteUseCase(ABC):
+    """Defines an abstract interface for deleting a Solve Job."""
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, solve_job_id: str) -> None:
+        """
+        Abstract method for deleting a Solve Job.
+
+        Parameters
+        ----------
+        solve_job_id : str
+            Unique identifier for the solve job to process.
+
+        Returns
+        -------
+        Model
+            The Model instance that corresponds to the processed job.
+
+        """

luna_quantum/solve/interfaces/usecases/solve_job_fetch_updates_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.solve_job import SolveJob
+
+
+class ISolveJobFetchUpdatesUseCase(ABC):
+    """Interface for fetching updates for a solve job.
+
+    Implementations of this interface must provide the logic for
+    initializing with a client and fetching updates when called.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        The client used for interacting with the solve job update service.
+    """
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, solve_job: SolveJob) -> None:
+        """
+        Abstract method for fetching updates for a solve job.
+
+        The fetched data will update the provided solve job object.
+
+        Parameters
+        ----------
+        solve_job : SolveJob
+            The solve job for which updates are to be fetched.
+        """

luna_quantum/solve/interfaces/usecases/solve_job_get_by_id_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.client.interfaces.services.luna_solve_i import ILunaSolve
+    from luna_quantum.solve.domain.solve_job import SolveJob
+
+
+class ISolveJobGetByIdUseCase(ABC):
+    """Represent an abstract base to retrieve a solve-job by its id."""
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(self, solve_job_id: str) -> SolveJob:
+        """
+        Represent an abstract base for callable objects to retrieve solve jobs.
+
+        Parameters
+        ----------
+        solve_job_id : str
+            The id of the solve-job to retrieve.
+        """

luna_quantum/solve/interfaces/usecases/solve_job_get_result_usecase_i.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luna_quantum 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.solve.domain.solve_job import SolveJob
+
+
+class ISolveJobGetResultUseCase(ABC):
+    """
+    Abstract base class for retrieving the solve job results.
+
+    This class defines an interface for operations related to solve job result
+    processing with specific parameters and behavior.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        The client responsible for interacting with the solve service.
+    """
+
+    @abstractmethod
+    def __init__(self, client: ILunaSolve) -> None:
+        pass
+
+    @abstractmethod
+    def __call__(
+        self,
+        solve_job: SolveJob,
+        sleep_time_max: float,
+        sleep_time_increment: float,
+        sleep_time_initial: float,
+        call_style: CallStyle,
+    ) -> Solution | None:
+        """
+        Callable method for retrieving the solve job results.
+
+        Abstract method for solving a given job with customizable retry settings,
+        including maximum sleep time, incremental sleep time adjustments, and
+        initial sleep time. The call style can also be specified.
+
+        Parameters
+        ----------
+        solve_job : SolveJob
+            The job to be solved.
+        sleep_time_max : float
+            Maximum sleep time allowed between retries in seconds.
+        sleep_time_increment : float
+            Incremental value added to sleep time after each retry in seconds.
+        sleep_time_initial : float
+            Initial sleep time before the first retry in seconds.
+        call_style : CallStyle
+            The style in which the job solving is conducted.
+
+        Returns
+        -------
+        Optional[Solution]
+            The solution to the job if solving is successful, otherwise None.
+        """

luna_quantum/solve/parameters/algorithms/__init__.py

@@ -0,0 +1,51 @@
+from .flexible_parameter_algorithm import FlexibleParameterAlgorithm
+from .genetic_algorithms import QAGA, SAGA
+from .lq_fda import FujitsuDA
+from .optimization_solvers import SCIP
+from .quantum_annealing import (
+    Kerberos,
+    LeapHybridBqm,
+    LeapHybridCqm,
+    ParallelTemperingQpu,
+    PopulationAnnealingQpu,
+    QBSolvLikeQpu,
+    QuantumAnnealing,
+    RepeatedReverseQuantumAnnealing,
+)
+from .quantum_gate import QAOA, QAOA_FO, VQE, FlexQAOA
+from .search_algorithms import DialecticSearch, QBSolvLikeTabuSearch, TabuSearch
+from .simulated_annealing import (
+    ParallelTempering,
+    PopulationAnnealing,
+    QBSolvLikeSimulatedAnnealing,
+    RepeatedReverseSimulatedAnnealing,
+    SimulatedAnnealing,
+)
+
+__all__ = [
+    "QAGA",
+    "QAOA",
+    "QAOA_FO",
+    "SAGA",
+    "SCIP",
+    "VQE",
+    "DialecticSearch",
+    "FlexQAOA",
+    "FlexibleParameterAlgorithm",
+    "FujitsuDA",
+    "Kerberos",
+    "LeapHybridBqm",
+    "LeapHybridCqm",
+    "ParallelTempering",
+    "ParallelTemperingQpu",
+    "PopulationAnnealing",
+    "PopulationAnnealingQpu",
+    "QBSolvLikeQpu",
+    "QBSolvLikeSimulatedAnnealing",
+    "QBSolvLikeTabuSearch",
+    "QuantumAnnealing",
+    "RepeatedReverseQuantumAnnealing",
+    "RepeatedReverseSimulatedAnnealing",
+    "SimulatedAnnealing",
+    "TabuSearch",
+]

luna_quantum/solve/parameters/algorithms/base_params/__init__.py

@@ -0,0 +1,24 @@
+from .decomposer import Decomposer
+from .qaoa_circuit_params import BasicQAOAParams, LinearQAOAParams, RandomQAOAParams
+from .quantum_annealing_params import QuantumAnnealingParams
+from .scipy_optimizer import ScipyOptimizerParams
+from .simulated_annealing_params import (
+    SimulatedAnnealingBaseParams,
+    SimulatedAnnealingParams,
+)
+from .tabu_kerberos_params import TabuKerberosParams
+from .tabu_search_params import TabuSearchBaseParams, TabuSearchParams
+
+__all__ = [
+    "BasicQAOAParams",
+    "Decomposer",
+    "LinearQAOAParams",
+    "QuantumAnnealingParams",
+    "RandomQAOAParams",
+    "ScipyOptimizerParams",
+    "SimulatedAnnealingBaseParams",
+    "SimulatedAnnealingParams",
+    "TabuKerberosParams",
+    "TabuSearchBaseParams",
+    "TabuSearchParams",
+]

luna_quantum/solve/parameters/algorithms/base_params/decomposer.py

@@ -0,0 +1,57 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class Decomposer(BaseModel):
+    """
+    Configuration for breaking down larger problems into subproblems for DWave QPUs.
+
+    Attributes
+    ----------
+    size: int, default=10
+        Nominal number of variables in each subproblem. The actual subproblem can be
+        smaller depending on other parameters (e.g., `min_gain`).
+
+    min_gain: Optional[float], default=None
+        Minimum required energy reduction threshold for including a variable in the
+        subproblem. A variable is included only if flipping its value reduces the
+        BQM energy by at least this amount. If None, no minimum gain is required.
+
+    rolling: bool, default=True
+        Controls variable selection strategy for successive calls on the same
+        problem:
+
+        - True: Produces subproblems on different variables by rolling down the list
+          of all variables sorted by decreasing impact
+        - False: Always selects variables with the highest impact
+
+    rolling_history: float, default=1.0
+        Fraction of the problem size (range 0.0 to 1.0) that participates in the
+        rolling selection. Once this fraction of variables has been processed,
+        subproblem unrolling is reset. Min: 0.0, Max: 1.0
+
+    silent_rewind: bool, default=True
+        Controls behavior when resetting/rewinding the subproblem generator:
+
+        - True: Silently rewind when the reset condition is met
+        - False: Raises EndOfStream exception when rewinding
+
+    traversal: Literal["energy", "bfs", "pfs"], default="energy"
+        Algorithm used to select a subproblem of `size` variables:
+
+        - "energy": Selects the next `size` variables ordered by descending energy
+          impact
+        - "bfs": Uses breadth-first traversal seeded by the next variable in the
+          energy impact list
+        - "pfs": Uses priority-first traversal seeded by variables from the energy
+          impact list, proceeding with the variable on the search boundary having
+          the highest energy impact
+    """
+
+    size: int = 10
+    min_gain: float | None = None
+    rolling: bool = True
+    rolling_history: float = Field(default=1.0, ge=0.0, le=1.0)
+    silent_rewind: bool = True
+    traversal: Literal["energy", "bfs", "pfs"] = "energy"

luna_quantum/solve/parameters/algorithms/base_params/qaoa_circuit_params.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import numpy as np
+from pydantic import BaseModel, Field, model_validator
+
+from luna_quantum.solve.errors.solve_base_error import SolveBaseError
+
+
+class QAOAParamsMismatchError(SolveBaseError):
+    """QAOA Parameters mismatch in length."""
+
+    def __init__(self, num_betas: int, num_gammas: int) -> None:
+        super().__init__(f"Parameter length must match: {num_betas=} {num_gammas=}")
+
+
+class BasicQAOAParams(BaseModel):
+    """Individual QAOA Parameters.
+
+    Parameters `betas` and `gammas` need to be of same size.
+
+    Attributes
+    ----------
+    betas: list[float]
+        List of beta parameters for the mixer layers in QAOA.
+    gammas: list[float]
+        List of gamma parameters for the cost layers in QAOA.
+    """
+
+    betas: list[float] = Field(
+        description="List of beta parameters for the mixer layers in QAOA."
+    )
+    gammas: list[float] = Field(
+        description="List of gamma parameters for the cost layers in QAOA."
+    )
+
+    @property
+    def reps(self) -> int:
+        """Returns the number of layers."""
+        return len(self.betas)
+
+    @model_validator(mode="after")
+    def _check_matching(self) -> BasicQAOAParams:
+        if len(self.betas) != len(self.gammas):
+            raise QAOAParamsMismatchError(len(self.betas), len(self.gammas))
+        return self
+
+
+class LinearQAOAParams(BaseModel):
+    """Linear QAOA Parameters.
+
+    Linearly decreasing beta parameters from `delta_beta` to zero. Linearly growing
+    paramters from zero to `delta_gamma`.
+
+    Attributes
+    ----------
+    delta_beta: float
+        Parameter scaling for the beta paramters for the mixer layers in QAOA.
+    delta_gamma: float
+        Parameters scaling for the gamma parameters for the cost layers in QAOA.
+    """
+
+    delta_beta: float = Field(
+        description="Parameter scaling for the beta paramters for the mixer layers in "
+        "QAOA."
+    )
+    delta_gamma: float = Field(
+        description="Parameters scaling for the gamma parameters for the cost layers "
+        "in QAOA."
+    )
+
+
+class RandomQAOAParams(BaseModel):
+    """Uniform random QAOA Parameter within predefined value ranges.
+
+    Attributes
+    ----------
+    seed: int | None
+        Seed for random number generator.
+    beta_range: tuple[float, float]
+        Value range for uniform random beta parameters (mixer layer).
+    gamma_range: tuple[float, float]
+        Value range for uniform random gamma parameters (cost layer).
+    """
+
+    seed: int | None = Field(
+        default=None, description="Seed for random number generator."
+    )
+    beta_range: tuple[float, float] = Field(
+        default=(0, 2 * np.pi),
+        description="Value range for uniform random beta parameters (mixer layer).",
+    )
+    gamma_range: tuple[float, float] = Field(
+        default=(0, 2 * np.pi),
+        description="Value range for uniform random gamma parameters (cost layer).",
+    )

luna_quantum/solve/parameters/algorithms/base_params/quantum_annealing_params.py

@@ -0,0 +1,79 @@
+from pydantic import BaseModel, Field
+
+
+class QuantumAnnealingParams(BaseModel):
+    """
+    Parameters for quantum annealing sampling on physical quantum processors (QPUs).
+
+    These parameters control the quantum annealing process on hardware devices like
+    D-Wave quantum annealers, specifying how the annealing is performed, how many
+    samples to collect, and various hardware-specific settings that affect solution
+    quality and runtime.
+
+    Attributes
+    ----------
+    anneal_offsets: list[float] | None
+        Per-qubit time offsets for the annealing path in normalized annealing time
+        units. List of floats with length equal to the number of qubits. Default is
+        None.
+    anneal_schedule: list[tuple[float, float]] | None
+        Custom schedule for the annealing process as a list of (time, s) pairs.
+        Time is in normalized units [0, 1] and s is the annealing parameter [0, 1].
+        Default is None.
+    annealing_time: float | None
+        Duration of the annealing process in microseconds. Must be within the range
+        supported by the QPU hardware. Default is None.
+    auto_scale: bool | None
+        Whether to automatically normalize the problem energy range to use the full
+        range of h and J values supported by the hardware. Default is None.
+    fast_anneal: bool
+        Use accelerated annealing protocol for shorter annealing times. Default is
+        False.
+    flux_biases: list[float] | None
+        Custom flux bias offsets for each qubit in units of Φ₀ (flux quantum).
+        List length must equal the number of qubits. Default is None.
+    flux_drift_compensation: bool
+        Whether to compensate for drift in qubit flux over time using real-time
+        calibration data. Default is True.
+    h_gain_schedule: list[tuple[float, float]] | None
+        Schedule for h-gain during annealing as a list of (time, gain) pairs.
+        Time is in normalized units [0, 1]. Default is None.
+    initial_state: list[int] | None
+        Starting state for the annealing process. List of {-1, +1} values with
+        length equal to the number of qubits. Default is None.
+    max_answers: int | None
+        Maximum number of unique answer states to return. Must be ≤ num_reads.
+        Default is None.
+    num_reads: int
+        Number of annealing cycles to perform. Must be positive integer.
+        Default is 1.
+    programming_thermalization: float | None
+        Wait time after programming the QPU in microseconds to allow the system
+        to thermalize. Default is None.
+    readout_thermalization: float | None
+        Wait time after each anneal before reading results in microseconds.
+        Default is None.
+    reduce_intersample_correlation: bool
+        Whether to add delay between samples to reduce correlation between
+        consecutive measurements. Default is False.
+    reinitialize_state: bool | None
+        Whether to reset to a new initial state between reads to reduce correlation.
+        Default is None.
+    """
+
+    anneal_offsets: list[float] | None = None
+    anneal_schedule: list[tuple[float, float]] | None = None
+    annealing_time: float | None = Field(default=None, gt=0)
+    auto_scale: bool | None = None
+    fast_anneal: bool = False
+    flux_biases: list[float] | None = None
+    flux_drift_compensation: bool = True
+    h_gain_schedule: list[tuple[float, float]] | None = None
+
+    initial_state: list[int] | None = None
+    max_answers: int | None = Field(default=None, ge=1)
+    num_reads: int = Field(default=1, ge=1)
+    programming_thermalization: float | None = Field(default=None, gt=0)
+    readout_thermalization: float | None = Field(default=None, gt=0)
+    reduce_intersample_correlation: bool = False
+    reinitialize_state: bool | None = None