luna-quantum 1.0.0__cp313-cp313-macosx_11_0_arm64.whl

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

@@ -0,0 +1,19 @@
+from .kerberos import Kerberos
+from .leap_hybrid_bqm import LeapHybridBqm
+from .leap_hybrid_cqm import LeapHybridCqm
+from .parallel_tempering_qpu import ParallelTemperingQpu
+from .population_annealing_qpu import PopulationAnnealingQpu
+from .qbsolv_like_qpu import QBSolvLikeQpu
+from .quantum_annealing import QuantumAnnealing
+from .repeated_reverse_quantum_annealing import RepeatedReverseQuantumAnnealing
+
+__all__ = [
+    "Kerberos",
+    "LeapHybridBqm",
+    "LeapHybridCqm",
+    "ParallelTemperingQpu",
+    "PopulationAnnealingQpu",
+    "QBSolvLikeQpu",
+    "QuantumAnnealing",
+    "RepeatedReverseQuantumAnnealing",
+]

luna_quantum/solve/parameters/algorithms/quantum_annealing/kerberos.py

@@ -0,0 +1,149 @@
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params import (
+    Decomposer,
+    QuantumAnnealingParams,
+    SimulatedAnnealingBaseParams,
+    TabuKerberosParams,
+)
+from luna_quantum.solve.parameters.backends import DWaveQpu
+from luna_quantum.solve.parameters.constants import (
+    DEFAULT_ATOL,
+    DEFAULT_RTOL,
+)
+
+
+class Kerberos(
+    LunaAlgorithm[DWaveQpu],
+):
+    """
+    Kerberos hybrid quantum-classical optimization solver.
+
+    Kerberos is a sophisticated hybrid solver that decomposes an optimization problem
+    into subproblems and solves them using multiple techniques in parallel: Tabu Search,
+    Simulated Annealing, and QPU (Quantum Processing Unit) sampling. It then combines
+    the results and iteratively refines the solution.
+
+    This approach leverages both classical and quantum resources efficiently, making it
+    effective for large and complex optimization problems beyond the capacity of pure
+    quantum approaches.
+
+    Attributes
+    ----------
+    num_reads: int
+        Number of output solutions to generate. Higher values provide better statistical
+        coverage of the solution space but increase computational resources required.
+        This parameter determines how many distinct solutions the algorithm will return
+        after completion. Default is 100.
+    num_retries: int
+        Number of attempts to retry embedding the problem onto the quantum hardware
+        if initial attempts fail. Useful for complex problems that may be challenging
+        to map to the quantum processor's topology. Each retry attempts a different
+        embedding strategy. Default is 0 (no retries).
+    max_iter: int | None
+        Maximum number of iterations for the solver. Each iteration involves running
+        the three solvers (Tabu, SA, QPU) in parallel, combining their results, and
+        refining the solution for the next iteration. Higher values allow more thorough
+        exploration and refinement but increase runtime. Default is 100.
+    max_time: int
+        Maximum time in seconds for the solver to run. Provides a hard time limit
+        regardless of convergence or iteration status. Once this time is reached,
+        the solver returns the best solution found so far. Default is 5, which may
+        need to be increased for large problems.
+    convergence: int
+        Number of consecutive iterations without improvement before declaring
+        convergence. Higher values ensure more stable solutions by requiring consistent
+        results across multiple iterations. Default is 3, which balances thoroughness
+        with efficiency.
+    target: float | None
+        Target objective value that triggers termination if reached. Allows early
+        stopping when a solution of sufficient quality is found. Default is None,
+        which means the algorithm will run until other stopping criteria are met.
+    rtol: float
+        Relative tolerance for convergence detection. Used when comparing objective
+        values between iterations to determine if significant improvement has occurred.
+        Smaller values require more substantial improvements to continue. Default is
+        DEFAULT_RTOL.
+    atol: float
+        Absolute tolerance for convergence detection. Used alongside rtol when
+        comparing objective values to determine if the algorithm has converged.
+        Smaller values enforce stricter convergence criteria. Default is DEFAULT_ATOL.
+    quantum_annealing_params: QuantumAnnealingParams
+        Nested configuration for quantum annealing parameters used by the QPU component
+        of the hybrid solver. Controls aspects like annealing schedule, chain strength,
+        and programming thermalization time. These parameters can significantly impact
+        the quality of solutions found by the quantum component. Default is a
+        QuantumAnnealingParams instance with default settings.
+    tabu_kerberos_params: TabuKerberosParams
+        Nested configuration for tabu search parameters used by the Tabu component of
+        the hybrid solver. Controls aspects like tabu tenure, number of iterations,
+        and neighborhood exploration strategy. The Tabu component helps the algorithm
+        systematically explore promising regions while avoiding cycles. Default is a
+        TabuKerberosParams instance with default settings.
+    decomposer: Decomposer
+        Decomposer: Breaks down problems into subproblems of manageable size
+        Default is a Decomposer instance with default settings.
+    """
+
+    num_reads: int = 100
+    num_retries: int = 0
+    max_iter: int | None = 100
+    max_time: int = 5
+    convergence: int = 3
+    target: float | None = None
+    rtol: float = DEFAULT_RTOL
+    atol: float = DEFAULT_ATOL
+    simulated_annealing_params: SimulatedAnnealingBaseParams = Field(
+        default_factory=SimulatedAnnealingBaseParams
+    )
+    quantum_annealing_params: QuantumAnnealingParams = Field(
+        default_factory=QuantumAnnealingParams
+    )
+    tabu_kerberos_params: TabuKerberosParams = Field(default_factory=TabuKerberosParams)
+    decomposer: Decomposer = Field(default_factory=Decomposer)
+
+    @property
+    def algorithm_name(self) -> str:
+        """
+        Returns the name of the algorithm.
+
+        This abstract property method is intended to be overridden by subclasses.
+        It should provide the name of the algorithm being implemented.
+
+        Returns
+        -------
+        str
+            The name of the algorithm.
+        """
+        return "K"
+
+    @classmethod
+    def get_default_backend(cls) -> DWaveQpu:
+        """
+        Return the default backend implementation.
+
+        This property must be implemented by subclasses to provide
+        the default backend instance to use when no specific backend
+        is specified.
+
+        Returns
+        -------
+            IBackend
+                An instance of a class implementing the IBackend interface that serves
+                as the default backend.
+        """
+        return DWaveQpu()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWaveQpu], ...]:
+        """
+        Check at runtime if the used backend is compatible with the solver.
+
+        Returns
+        -------
+        tuple[type[IBackend], ...]
+            True if the backend is compatible with the solver, False otherwise.
+
+        """
+        return (DWaveQpu,)

luna_quantum/solve/parameters/algorithms/quantum_annealing/leap_hybrid_bqm.py

@@ -0,0 +1,75 @@
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.backends import DWaveQpu
+
+
+class LeapHybridBqm(LunaAlgorithm[DWaveQpu]):
+    """
+    D-Wave's Leap Hybrid Binary Quadratic Model (BQM) solver.
+
+    Leap's hybrid BQM solver is a cloud-based service that combines quantum and
+    classical resources to solve unconstrained binary optimization problems that are
+    larger than what can fit directly on a quantum processor. It automatically handles
+    decomposition, quantum processing, and solution reconstruction.
+
+    The hybrid solver is particularly useful for problems with thousands of variables,
+    offering better scaling than classical solvers for many problem types.
+
+    Attributes
+    ----------
+    time_limit: float | int | None
+        Maximum running time in seconds. Longer time limits generally produce better
+        solutions but increase resource usage and cost. Default is None, which uses
+        the service's default time limit (typically problem-size dependent).
+
+    Note
+    ------
+    For a D-Wave backend, this will ignore the decompose parameters as the hybrid
+    solver handles decomposition internally.
+    """
+
+    time_limit: float | int | None = None
+
+    @property
+    def algorithm_name(self) -> str:
+        """
+        Returns the name of the algorithm.
+
+        This abstract property method is intended to be overridden by subclasses.
+        It should provide the name of the algorithm being implemented.
+
+        Returns
+        -------
+        str
+            The name of the algorithm.
+        """
+        return "LBQM"
+
+    @classmethod
+    def get_default_backend(cls) -> DWaveQpu:
+        """
+        Return the default backend implementation.
+
+        This property must be implemented by subclasses to provide
+        the default backend instance to use when no specific backend
+        is specified.
+
+        Returns
+        -------
+            IBackend
+                An instance of a class implementing the IBackend interface that serves
+                as the default backend.
+        """
+        return DWaveQpu()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWaveQpu], ...]:
+        """
+        Check at runtime if the used backend is compatible with the solver.
+
+        Returns
+        -------
+        tuple[type[IBackend], ...]
+            True if the backend is compatible with the solver, False otherwise.
+
+        """
+        return (DWaveQpu,)

luna_quantum/solve/parameters/algorithms/quantum_annealing/leap_hybrid_cqm.py

@@ -0,0 +1,75 @@
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.backends import DWaveQpu
+
+
+class LeapHybridCqm(LunaAlgorithm[DWaveQpu]):
+    """
+    Parameters for D-Wave's Leap Hybrid Constrained Quadratic Model (CQM) solver.
+
+    The Leap Hybrid CQM solver extends hybrid quantum-classical optimization to handle
+    constrained problems, allowing both linear and quadratic constraints alongside
+    the quadratic objective function. This enables solving many practical optimization
+    problems in their natural formulation without manual penalty conversion.
+
+    The solver is suitable for mixed binary, integer, and continuous problems with
+    thousands of variables and constraints.
+
+    Attributes
+    ----------
+    time_limit: float | int | None
+        Maximum running time in seconds. Longer limits generally yield better solutions
+        but increase resource usage. Default is None, which uses the service's default
+        time limit (typically problem-size dependent).
+    spin_variables: list[str] | None
+        Variables to represent as spins (-1/+1) rather than binary (0/1) values.
+        Useful for problems naturally formulated in spin space. Default is None,
+        which uses binary representation for all discrete variables.
+    """
+
+    time_limit: float | int | None = None
+    spin_variables: list[str] | None = None
+
+    @property
+    def algorithm_name(self) -> str:
+        """
+        Returns the name of the algorithm.
+
+        This abstract property method is intended to be overridden by subclasses.
+        It should provide the name of the algorithm being implemented.
+
+        Returns
+        -------
+        str
+            The name of the algorithm.
+        """
+        return "LCQM"
+
+    @classmethod
+    def get_default_backend(cls) -> DWaveQpu:
+        """
+        Return the default backend implementation.
+
+        This property must be implemented by subclasses to provide
+        the default backend instance to use when no specific backend
+        is specified.
+
+        Returns
+        -------
+            IBackend
+                An instance of a class implementing the IBackend interface that serves
+                as the default backend.
+        """
+        return DWaveQpu()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWaveQpu], ...]:
+        """
+        Check at runtime if the used backend is compatible with the solver.
+
+        Returns
+        -------
+        tuple[type[IBackend], ...]
+            True if the backend is compatible with the solver, False otherwise.
+
+        """
+        return (DWaveQpu,)

luna_quantum/solve/parameters/algorithms/quantum_annealing/parallel_tempering_qpu.py

@@ -0,0 +1,139 @@
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params import (
+    Decomposer,
+    QuantumAnnealingParams,
+)
+from luna_quantum.solve.parameters.backends import DWaveQpu
+from luna_quantum.solve.parameters.constants import DEFAULT_ATOL, DEFAULT_RTOL
+
+
+class ParallelTemperingQpu(
+    LunaAlgorithm[DWaveQpu],
+):
+    """
+    Parameters for the Parallel Tempering QPU solver.
+
+    Parallel Tempering uses multiple model procedures per temperature.
+    During the cooling process, an exchange of replicas can take place between the
+    parallel procedures, thus enabling higher energy mountains to be overcome.
+
+    Attributes
+    ----------
+    n_replicas: int
+        Number of system replicas to simulate at different temperatures. More replicas
+        provide better temperature coverage but increase computational cost.
+        Default is 2, which is minimal but can still provide benefits over
+        single-temperature methods.
+    random_swaps_factor: int
+        Factor controlling how frequently random swap attempts occur between replicas.
+        Higher values increase mixing between replicas but add overhead.
+        Default is 1, balancing mixing with efficiency.
+    max_iter: int | None
+        Maximum number of iterations. Controls how many rounds of replica exchange
+        are performed. Higher values allow more thorough exploration.
+        Default is 100.
+    max_time: int
+        Maximum time in seconds that the algorithm is allowed to run.
+        Default is 5.
+    convergence: int
+        Number of consecutive iterations with no improvement required to consider
+        the algorithm converged. Default is 3.
+    target: float | None
+        Target energy value. If reached, the algorithm will terminate.
+        Default is None, meaning no target is set.
+    rtol: float
+        Relative tolerance for convergence checking. Default is DEFAULT_RTOL.
+    atol: float
+        Absolute tolerance for convergence checking. Default is DEFAULT_ATOL.
+    num_reads: int
+        Number of annealing cycles to perform on the D-Wave QPU. Default is 100.
+    num_retries: int
+        Number of attempts to retry embedding the problem onto the quantum hardware.
+        Default is 0.
+    fixed_temp_sampler_num_sweeps: int
+        Number of Monte Carlo sweeps to perform, where one sweep attempts to update all
+        variables once. More sweeps produce better equilibrated samples but increase
+        computation time. Default is 10,000, which is suitable for thorough exploration
+        of moderate-sized problems.
+    fixed_temp_sampler_num_reads: int | None
+        Number of independent sampling runs to perform. Each run produces one sample
+        from the equilibrium distribution. Multiple reads provide better statistical
+        coverage of the solution space. Default is None, which typically defaults to 1
+        or matches the number of initial states provided.
+    quantum_annealing_params: QuantumAnnealingParams
+        Configuration for the quantum annealing process on D-Wave hardware.
+        Contains settings for anneal schedule, flux biases, and other QPU-specific
+        parameters. See QuantumAnnealingParams documentation for details.
+    decomposer: Decomposer
+        Decomposer: Breaks down problems into subproblems of manageable size
+        Default is a Decomposer instance with default settings.
+    """
+
+    n_replicas: int = 2
+    random_swaps_factor: int = 1
+    max_iter: int | None = 100
+    max_time: int = 5
+    convergence: int = 3
+    target: float | None = None
+    rtol: float = DEFAULT_RTOL
+    atol: float = DEFAULT_ATOL
+
+    num_reads: int = 100
+    num_retries: int = 0
+
+    fixed_temp_sampler_num_sweeps: int = 10_000
+    fixed_temp_sampler_num_reads: int | None = None
+
+    quantum_annealing_params: QuantumAnnealingParams = Field(
+        default_factory=QuantumAnnealingParams
+    )
+
+    decomposer: Decomposer = Field(default_factory=Decomposer)
+
+    # does not support random_swaps_factor variable of parallel tempering parameters
+    @property
+    def algorithm_name(self) -> str:
+        """
+        Returns the name of the algorithm.
+
+        This abstract property method is intended to be overridden by subclasses.
+        It should provide the name of the algorithm being implemented.
+
+        Returns
+        -------
+        str
+            The name of the algorithm.
+        """
+        return "PTQ"
+
+    @classmethod
+    def get_default_backend(cls) -> DWaveQpu:
+        """
+        Return the default backend implementation.
+
+        This property must be implemented by subclasses to provide
+        the default backend instance to use when no specific backend
+        is specified.
+
+        Returns
+        -------
+            IBackend
+                An instance of a class implementing the IBackend interface that serves
+                as the default backend.
+        """
+        return DWaveQpu()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWaveQpu], ...]:
+        """
+        Check at runtime if the used backend is compatible with the solver.
+
+        Returns
+        -------
+        tuple[type[IBackend], ...]
+            True if the backend is compatible with the solver, False otherwise.
+
+        """
+        return (DWaveQpu,)

luna_quantum/solve/parameters/algorithms/quantum_annealing/population_annealing_qpu.py

@@ -0,0 +1,109 @@
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params import (
+    Decomposer,
+    QuantumAnnealingParams,
+)
+from luna_quantum.solve.parameters.backends import DWaveQpu
+
+
+class PopulationAnnealingQpu(LunaAlgorithm[DWaveQpu]):
+    """
+    Parameters for the Population Annealing QPU algorithm.
+
+    Population Annealing uses a sequential Monte Carlo method to minimize the energy of
+    a population. The population consists of walkers that can explore their
+    neighborhood during the cooling process. Afterwards, walkers are removed and
+    duplicated using bias to lower energy. Eventually, a population collapse occurs
+    where all walkers are in the lowest energy state.
+
+    Attributes
+    ----------
+    num_reads: int
+        Number of annealing cycles to perform on the D-Wave QPU. Default is 100.
+    num_retries: int
+        Number of attempts to retry embedding the problem onto the quantum hardware.
+        Default is 0.
+    max_iter: int
+        Maximum number of iterations. Controls how many rounds of annealing and
+        population adjustments are performed. Default is 20.
+    max_time: int
+        Maximum time in seconds that the algorithm is allowed to run. Serves as
+        a stopping criterion alongside max_iter. Default is 2.
+    fixed_temp_sampler_num_sweeps: int
+        Number of Monte Carlo sweeps to perform, where one sweep attempts to update all
+        variables once. More sweeps produce better equilibrated samples but increase
+        computation time. Default is 10,000, which is suitable for thorough exploration
+        of moderate-sized problems.
+    fixed_temp_sampler_num_reads: int | None
+        Number of independent sampling runs to perform. Each run produces one sample
+        from the equilibrium distribution. Multiple reads provide better statistical
+        coverage of the solution space. Default is None, which typically defaults to 1
+        or matches the number of initial states provided.
+    decomposer: Decomposer
+        Decomposer: Breaks down problems into subproblems of manageable size
+        Default is a Decomposer instance with default settings.
+    quantum_annealing_params: QuantumAnnealingParams
+        Parameters that control the quantum annealing process, including annealing
+        schedule, temperature settings, and other quantum-specific parameters. These
+        settings determine how the system transitions from quantum superposition to
+        classical states during the optimization process.
+    """
+
+    num_reads: int = 100
+    num_retries: int = 0
+    max_iter: int = 20
+    max_time: int = 2
+    fixed_temp_sampler_num_sweeps: int = 10_000
+    fixed_temp_sampler_num_reads: int | None = None
+    decomposer: Decomposer = Field(default_factory=Decomposer)
+
+    quantum_annealing_params: QuantumAnnealingParams = Field(
+        default_factory=QuantumAnnealingParams
+    )
+
+    @property
+    def algorithm_name(self) -> str:
+        """
+        Returns the name of the algorithm.
+
+        This abstract property method is intended to be overridden by subclasses.
+        It should provide the name of the algorithm being implemented.
+
+        Returns
+        -------
+        str
+            The name of the algorithm.
+        """
+        return "PAQ"
+
+    @classmethod
+    def get_default_backend(cls) -> DWaveQpu:
+        """
+        Return the default backend implementation.
+
+        This property must be implemented by subclasses to provide
+        the default backend instance to use when no specific backend
+        is specified.
+
+        Returns
+        -------
+            IBackend
+                An instance of a class implementing the IBackend interface that serves
+                as the default backend.
+        """
+        return DWaveQpu()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWaveQpu], ...]:
+        """
+        Check at runtime if the used backend is compatible with the solver.
+
+        Returns
+        -------
+        tuple[type[IBackend], ...]
+            True if the backend is compatible with the solver, False otherwise.
+
+        """
+        return (DWaveQpu,)

luna_quantum/solve/parameters/algorithms/quantum_annealing/qbsolv_like_qpu.py

@@ -0,0 +1,111 @@
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params import (
+    Decomposer,
+    QuantumAnnealingParams,
+)
+from luna_quantum.solve.parameters.backends import DWaveQpu
+from luna_quantum.solve.parameters.mixins.qbsolv_like_mixin import QBSolvLikeMixin
+
+
+class QBSolvLikeQpu(QBSolvLikeMixin, LunaAlgorithm[DWaveQpu]):
+    """
+    QBSolv-like algorithm for QPU.
+
+    QBSolv QPU splits the problem into parts and solves them using the Tabu Search
+    algorithm. For this purpose, the DWaveSampler is used.
+
+    Attributes
+    ----------
+    decomposer_size: int
+        Size for the decomposer. Determines the maximum subproblem size to be sent to
+        the quantum processor, with larger values potentially improving solution quality
+        at the cost of increased processing time.
+    rolling: bool
+        Whether to use rolling for the solver. When enabled, this allows for smoother
+        transitions between subproblems during the decomposition process.
+    rolling_history: float
+        Rolling history parameter for the solver. Controls how much previous iteration
+        information is considered when solving subsequent subproblems.
+    max_iter: int | None
+        Maximum number of iterations. Limits the total number of decomposition and
+        solving cycles performed by the algorithm.
+    max_time: int
+        Time in seconds after which the algorithm will stop. Provides a time-based
+        stopping criterion regardless of convergence status.
+    convergence: int
+        Number of iterations with unchanged output to terminate algorithm. Higher values
+        ensure more stable solutions but may increase computation time.
+    target: float | None
+        Energy level that the algorithm tries to reach. If this target energy is
+        achieved, the algorithm will terminate early.
+    rtol: float
+        Relative tolerance for convergence. Used when comparing energy values between
+        iterations to determine if convergence has been reached.
+    atol: float
+        Absolute tolerance for convergence. Used alongside rtol when comparing energy
+        values to determine convergence.
+    num_reads: int
+        Number of reads for the solver.
+    num_retries: int
+        Number of retries for the solver.
+    quantum_annealing_params: QuantumAnnealingParams
+        Quantum annealing parameters.
+    decomposer: Decomposer
+        Decomposer: Breaks down problems into subproblems of manageable size
+        Default is a Decomposer instance with default settings.
+    """
+
+    num_reads: int = 100
+    num_retries: int = 0
+
+    quantum_annealing_params: QuantumAnnealingParams = Field(
+        default_factory=QuantumAnnealingParams
+    )
+    decomposer: Decomposer = Field(default_factory=Decomposer)
+
+    @property
+    def algorithm_name(self) -> str:
+        """
+        Returns the name of the algorithm.
+
+        This abstract property method is intended to be overridden by subclasses.
+        It should provide the name of the algorithm being implemented.
+
+        Returns
+        -------
+        str
+            The name of the algorithm.
+        """
+        return "QLQ"
+
+    @classmethod
+    def get_default_backend(cls) -> DWaveQpu:
+        """
+        Return the default backend implementation.
+
+        This property must be implemented by subclasses to provide
+        the default backend instance to use when no specific backend
+        is specified.
+
+        Returns
+        -------
+            IBackend
+                An instance of a class implementing the IBackend interface that serves
+                as the default backend.
+        """
+        return DWaveQpu()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWaveQpu], ...]:
+        """
+        Check at runtime if the used backend is compatible with the solver.
+
+        Returns
+        -------
+        tuple[type[IBackend], ...]
+            True if the backend is compatible with the solver, False otherwise.
+
+        """
+        return (DWaveQpu,)