luna-quantum 1.0.0__cp312-cp312-musllinux_1_2_x86_64.whl

luna_quantum/solve/parameters/algorithms/search_algorithms/qbsolv_like_tabu_search.py

@@ -0,0 +1,117 @@
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params.tabu_search_params import (
+    TabuSearchBaseParams,
+)
+from luna_quantum.solve.parameters.backends import DWave
+from luna_quantum.solve.parameters.mixins.qbsolv_like_mixin import QBSolvLikeMixin
+
+
+class QBSolvLikeTabuSearch(QBSolvLikeMixin, LunaAlgorithm[DWave]):
+    """QbSolvLikeTabuSearch Parameters.
+
+    QBSolv Like Tabu Search breaks down the problem and solves the parts individually
+    using a classic solver that uses Tabu Search. This particular implementation uses
+    hybrid.TabuSubproblemSampler (https://docs.ocean.dwavesys.com/projects/hybrid/en/stable/reference/samplers.html#tabusubproblemsampler)
+    as a sampler for the subproblems to achieve a QBSolv like behaviour.
+
+    This class combines parameters from two sources:
+    - QBSolvLikeMixin: Provides parameters for the QBSolv-like decomposition approach
+    - tabu_search_params: Nested parameter object for Tabu Search configuration
+
+    Attributes
+    ----------
+    decomposer_size: int
+        Size for the decomposer, which determines the maximum subproblem size to be
+        handled in each iteration. Larger values may produce better solutions but
+        increase computational complexity exponentially. Default is 50, which balances
+        solution quality with reasonable runtime.
+    rolling: bool
+        Whether to use rolling window decomposition for the solver. When enabled,
+        this allows for overlapping subproblems with shared variables, which can
+        improve solution quality by better handling interactions across subproblem
+        boundaries. Default is True.
+    rolling_history: float
+        Rolling history factor controlling how much of previous subproblem solutions
+        are considered when solving subsequent subproblems. Higher values incorporate
+        more historical information but may slow convergence to new solutions.
+        Default is 0.15 (15% retention).
+    max_iter: int | None
+        Maximum number of iterations (decomposition and solving cycles) to perform.
+        Higher values allow for more thorough optimization but increase runtime.
+        Default is 100.
+    max_time: int
+        Time in seconds after which the algorithm will stop, regardless of convergence
+        status. Provides a hard time limit for time-constrained applications.
+        Default is 5.
+    convergence: int
+        Number of iterations with unchanged output to terminate algorithm. Higher values
+        ensure more stable solutions but may increase computation time unnecessarily
+        if the algorithm has already found the best solution. Default is 3.
+    target: float | None
+        Energy level that the algorithm tries to reach. If this target energy is
+        achieved, the algorithm will terminate early. Default is None, meaning the
+        algorithm will run until other stopping criteria are met.
+    rtol: float
+        Relative tolerance for convergence. Used when comparing energy values between
+        iterations to determine if significant improvement has occurred. Default uses
+        DEFAULT_RTOL.
+    atol: float
+        Absolute tolerance for convergence. Used alongside rtol when comparing energy
+        values to determine if the algorithm has converged. Default uses DEFAULT_ATOL.
+    tabu_search_params: TabuSearchBaseParams
+        Nested configuration for Tabu Search algorithm parameters. Controls the
+        behavior of the Tabu Search used to solve each subproblem, including
+        parameters like tabu tenure, number of restarts, and timeout conditions.
+        See TabuSearchParams class for details of contained parameters.
+    """
+
+    tabu_search_params: TabuSearchBaseParams = Field(
+        default_factory=TabuSearchBaseParams
+    )
+
+    @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 "QLTS"
+
+    @classmethod
+    def get_default_backend(cls) -> DWave:
+        """
+        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 DWave()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWave], ...]:
+        """
+        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 (DWave,)

luna_quantum/solve/parameters/algorithms/search_algorithms/tabu_search.py

@@ -0,0 +1,126 @@
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params.tabu_search_params import (
+    TabuSearchParams,
+)
+from luna_quantum.solve.parameters.backends import DWave
+
+
+class TabuSearch(TabuSearchParams, LunaAlgorithm[DWave]):
+    """
+    Extended parameters for the Tabu Search optimization algorithm.
+
+    Tabu Search is a metaheuristic that enhances local search by maintaining a
+    "tabu list" of recently visited solutions to avoid cycling. It systematically
+    explores the solution space by allowing non-improving moves when no improving moves
+    exist, while preventing revisiting recent solutions.
+
+    This class extends the basic TabuSearch with additional parameters for fine-tuning
+    the search process, including restart strategies and early termination conditions.
+
+    Attributes
+    ----------
+    initial_states: Any | None
+        Starting states for the search. Allows the algorithm to begin from promising
+        regions rather than random points. If fewer states than num_reads are provided,
+        additional states are generated according to initial_states_generator.
+        Default is None (random starting states).
+    seed: int | None
+        Random seed for reproducible results. With identical parameters and seed,
+        results will be identical (unless timeout limits are reached, as finite
+        clock resolution can affect execution). Default is None (random seed).
+    num_restarts: int
+        Maximum number of tabu search restarts per read. Restarts help escape deep
+        local minima by starting fresh from new points after the initial search stalls.
+        Setting to zero results in a simple tabu search without restarts.
+        Default is 1,000,000, allowing many restarts if needed.
+    energy_threshold: float | None
+        Target energy value that triggers termination if found. Allows early stopping
+        when a sufficiently good solution is discovered. Default is None (run until
+        other stopping criteria are met).
+    coefficient_z_first: int | None
+        Controls the number of variable updates in the first simple tabu search (STS).
+        The actual limit is max(variables*coefficient_z_first, lower_bound_z).
+        Defaults to 10,000 for small problems (≤500 variables) and 25,000 for larger
+        ones. Higher values allow more thorough exploration of the initial solution
+        neighborhood.
+    coefficient_z_restart: int | None
+        Controls the number of variable updates in restarted tabu searches.
+        Similar to coefficient_z_first but for restart phases. Default is
+        coefficient_z_first/4, allowing faster exploration during restarts. This
+        typically results in broader but less deep searches after restarts.
+    lower_bound_z: int | None
+        Minimum number of variable updates for all tabu searches. Ensures a thorough
+        search even for small problems. Default is 500,000. Setting too low may
+        result in premature termination before finding good solutions.
+    num_reads: int | None
+        Number of independent runs of the tabu algorithm, each producing one solution.
+        Multiple reads increase the chance of finding the global optimum by starting
+        from different initial states. If None, matches the number of initial states
+        provided (or performs just one read if no initial states are given).
+    tenure: int | None
+        Length of the tabu list - the number of recently visited solutions that are
+        forbidden. Larger values help escape deeper local minima but may slow
+        exploration. Default is 1/4 of the number of variables up to a maximum of 20.
+        A good tenure balances diversification (exploring new regions) with
+        intensification (focusing on promising areas).
+    timeout: float
+        Maximum running time in milliseconds per read before the algorithm stops,
+        regardless of convergence. Default is 100, which is suitable for small to
+        medium-sized problems. For larger problems, consider increasing this value
+        to allow sufficient exploration time.
+    initial_states_generator: Literal["none", "tile", "random"]
+        Controls how to handle situations where fewer initial states are provided
+        than num_reads:
+
+        - "none": Raises an error if insufficient initial states
+        - "tile": Reuses provided states by cycling through them
+        - "random": Generates additional random states as needed
+
+        Default is "random", which maximizes search space coverage when the number
+        of provided initial states is insufficient.
+    """
+
+    @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 "TS"
+
+    @classmethod
+    def get_default_backend(cls) -> DWave:
+        """
+        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 DWave()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWave], ...]:
+        """
+        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 (DWave,)

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

@@ -0,0 +1,13 @@
+from .parallel_tempering import ParallelTempering
+from .population_annealing import PopulationAnnealing
+from .qbsolv_like_simulated_annealing import QBSolvLikeSimulatedAnnealing
+from .repeated_reverse_simulated_annealing import RepeatedReverseSimulatedAnnealing
+from .simulated_annealing import SimulatedAnnealing
+
+__all__ = [
+    "ParallelTempering",
+    "PopulationAnnealing",
+    "QBSolvLikeSimulatedAnnealing",
+    "RepeatedReverseSimulatedAnnealing",
+    "SimulatedAnnealing",
+]

luna_quantum/solve/parameters/algorithms/simulated_annealing/parallel_tempering.py

@@ -0,0 +1,131 @@
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.backends import DWave
+from luna_quantum.solve.parameters.constants import DEFAULT_ATOL, DEFAULT_RTOL
+
+
+class ParallelTempering(LunaAlgorithm[DWave]):
+    """
+    Parameters for the Parallel Tempering (replica exchange) optimization algorithm.
+
+    Parallel Tempering runs multiple copies ("replicas") of the system simultaneously
+    at different temperatures. Periodically, replicas at adjacent temperatures can swap
+    configurations, allowing high-temperature replicas to explore widely while
+    low-temperature replicas exploit promising regions.
+
+    This approach is particularly effective for problems with many local minima, as it
+    combines the exploration benefits of high temperature with the exploitation benefits
+    of low temperature.
+
+    Attributes
+    ----------
+    n_replicas: int
+        Number of system replicas to simulate at different temperatures. More replicas
+        provide better temperature coverage but increase computational cost.
+        Higher values allow for finer gradations between temperature levels, potentially
+        improving the exchange of configurations between adjacent replicas.
+        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 computational overhead.
+        More frequent swaps help configurations move more quickly between temperature
+        levels, allowing good solutions found at high temperatures to be refined at
+        lower temperatures. Default is 1, balancing mixing with efficiency.
+    max_iter: int | None
+        Maximum number of iterations (temperature cycles) to perform. Each iteration
+        involves sampling at all temperature levels and attempting exchanges between
+        replicas. Higher values allow more thorough exploration but increase runtime.
+        Default is 100.
+    max_time: int
+        Maximum time in seconds for the algorithm to run. Provides a hard time limit
+        regardless of convergence or iteration status. Useful for time-constrained
+        scenarios where some solution is needed within a specific timeframe.
+        Default is 5.
+    convergence: int
+        Number of consecutive iterations without improvement before declaring
+        convergence. Higher values ensure more stable solutions but may increase
+        computation time unnecessarily if the algorithm has already found the best
+        solution. Default is 3.
+    target: float | None
+        Target objective value that triggers termination if reached. Allows early
+        stopping when a sufficiently good solution 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.
+        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. Default is
+        DEFAULT_ATOL.
+    fixed_temp_sampler_num_sweeps: int
+        Number of Monte Carlo sweeps to perform at each temperature level, where one
+        sweep attempts to update all variables once. More sweeps produce better
+        equilibrated samples but increase computation time. This parameter controls
+        how thoroughly each replica explores its local solution space before exchange
+        attempts. 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 at each temperature level.
+        Each run produces one sample from the equilibrium distribution. Multiple reads
+        provide better statistical coverage of the solution space at each temperature.
+        Default is None, which typically defaults to 1 or matches the number of initial
+        states provided.
+    """
+
+    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
+
+    fixed_temp_sampler_num_sweeps: int = 10_000
+    fixed_temp_sampler_num_reads: 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 "PT"
+
+    @classmethod
+    def get_default_backend(cls) -> DWave:
+        """
+        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 DWave()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWave], ...]:
+        """
+        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 (DWave,)

luna_quantum/solve/parameters/algorithms/simulated_annealing/population_annealing.py

@@ -0,0 +1,95 @@
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.backends import DWave
+
+
+class PopulationAnnealing(LunaAlgorithm[DWave]):
+    """
+    Parameters for the Population Annealing 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
+    ----------
+    max_iter: int
+        Maximum number of annealing iterations (temperature steps) to perform. Each
+        iteration involves lowering the temperature, allowing walkers to explore
+        locally, and then resampling the population based on Boltzmann weights.
+        Higher values allow for a more gradual cooling schedule, potentially finding
+        better solutions but increasing computation time. Default is 20,
+        which provides a reasonable balance for most problems.
+    max_time: int
+        Maximum time in seconds that the algorithm is allowed to run. Provides a hard
+        time limit regardless of convergence or iteration status. Useful for
+        time-constrained scenarios where some solution is needed within a specific
+        timeframe. Default is 2, which is relatively aggressive and may need to be
+        increased for complex problems.
+    fixed_temp_sampler_num_sweeps: int
+        Number of Monte Carlo sweeps to perform at each temperature level, where one
+        sweep attempts to update all variables once. More sweeps allow walkers to
+        explore their local configuration space more thoroughly, producing better
+        equilibrated samples but increasing computation time. This parameter directly
+        affects how well each walker samples its local energy landscape before
+        resampling occurs. 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 at each temperature level.
+        Each run effectively initializes a separate walker in the population. Multiple
+        reads provide better coverage of the solution space, increasing the diversity
+        of the initial population and improving the chances of finding the global
+        optimum. Default is None, which typically defaults to 1 or matches the number
+    """
+
+    max_iter: int = 20
+    max_time: int = 2
+
+    fixed_temp_sampler_num_sweeps: int = 10_000
+    fixed_temp_sampler_num_reads: 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 "PA"
+
+    @classmethod
+    def get_default_backend(cls) -> DWave:
+        """
+        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 DWave()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWave], ...]:
+        """
+        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 (DWave,)

luna_quantum/solve/parameters/algorithms/simulated_annealing/qbsolv_like_simulated_annealing.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params import (
+    SimulatedAnnealingBaseParams,
+)
+from luna_quantum.solve.parameters.backends import DWave
+from luna_quantum.solve.parameters.mixins.qbsolv_like_mixin import QBSolvLikeMixin
+
+
+class QBSolvLikeSimulatedAnnealing(LunaAlgorithm[DWave], QBSolvLikeMixin):
+    """
+    QBSolv Like Simulated Annealing solver.
+
+    QBSolv Like Simulated Annealing breaks down the problem and solves the parts
+    individually using a classic solver that uses Simulated Annealing.
+    This particular implementation uses hybrid.SimulatedAnnealingSubproblemSampler
+    (https://docs.ocean.dwavesys.com/projects/hybrid/en/stable/reference/samplers.html#simulatedannealingsubproblemsampler)
+    as a sampler for the subproblems to achieve a QBSolv like behaviour.
+
+    This class combines parameters from multiple sources:
+    - QBSolvLikeMixin: Provides parameters for the QBSolv-like decomposition approach
+    - SimulatedAnnealingParams: Provides parameters specific to simulated annealing
+
+    Attributes
+    ----------
+        decomposer_size: int
+        Size for the decomposer, which determines the maximum subproblem size to be
+        handled in each iteration. Larger values may produce better solutions but
+        increase computational complexity exponentially. Default is 50, which balances
+        solution quality with reasonable runtime.
+    rolling: bool
+        Whether to use rolling window decomposition for the solver. When enabled,
+        this allows for overlapping subproblems with shared variables, which can
+        improve solution quality by better handling interactions across subproblem
+        boundaries. Default is True.
+    rolling_history: float
+        Rolling history factor controlling how much of previous subproblem solutions
+        are considered when solving subsequent subproblems. Higher values incorporate
+        more historical information but may slow convergence to new solutions.
+        Default is 0.15 (15% retention).
+    max_iter: int | None
+        Maximum number of iterations (decomposition and solving cycles) to perform.
+        Higher values allow for more thorough optimization but increase runtime.
+        Default is 100.
+    max_time: int
+        Time in seconds after which the algorithm will stop, regardless of convergence
+        status. Provides a hard time limit for time-constrained applications.
+        Default is 5.
+    convergence: int
+        Number of iterations with unchanged output to terminate algorithm. Higher values
+        ensure more stable solutions but may increase computation time unnecessarily
+        if the algorithm has already found the best solution. Default is 3.
+    target: float | None
+        Energy level that the algorithm tries to reach. If this target energy is
+        achieved, the algorithm will terminate early. Default is None, meaning the
+        algorithm will run until other stopping criteria are met.
+    rtol: float
+        Relative tolerance for convergence. Used when comparing energy values between
+        iterations to determine if significant improvement has occurred. Default uses
+        DEFAULT_RTOL.
+    atol: float
+        Absolute tolerance for convergence. Used alongside rtol when comparing energy
+        values to determine if the algorithm has converged. Default uses DEFAULT_ATOL.
+    num_reads : Union[int, None]
+        Number of independent runs of the algorithm, each producing one solution sample.
+        Multiple reads with different random starting points increase the chance of
+        finding the global optimum. Default is None, which matches the number of initial
+        states (or just one read if no initial states are provided).
+    num_sweeps : Union[int, None]
+        Number of iterations/sweeps per run, where each sweep updates all variables
+        once. More sweeps allow more thorough exploration but increase runtime.
+        Default is 1,000, suitable for small to medium problems.
+    beta_range : Union[List[float], Tuple[float, float], None]
+        The inverse temperature (β=1/T) schedule endpoints, specified as [start, end].
+        A wider range allows more exploration. Default is calculated based on the
+        problem's energy scale to ensure appropriate acceptance probabilities.
+    beta_schedule_type : Literal["linear", "geometric"]
+        How beta values change between endpoints:
+        - "linear": Equal steps (β₁, β₂, ...) - smoother transitions
+        - "geometric": Multiplicative steps (β₁, r·β₁, r²·β₁, ...) - spends more time at
+          lower temperatures for fine-tuning
+        Default is "geometric", which often performs better for optimization problems.
+    initial_states_generator : Literal["none", "tile", "random"]
+        How to handle cases with fewer initial states than num_reads:
+        - "none": Raises error if insufficient initial states
+        - "tile": Reuses provided states by cycling through them
+        - "random": Generates additional random states as needed
+        Default is "random", which maximizes exploration.
+    """
+
+    simulated_annealing: SimulatedAnnealingBaseParams = Field(
+        default_factory=SimulatedAnnealingBaseParams
+    )
+
+    @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 "QLSA"
+
+    @classmethod
+    def get_default_backend(cls) -> DWave:
+        """
+        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 DWave()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWave]]:
+        """
+        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 (DWave,)