luna-quantum 1.0.8rc2__cp314-cp314-win_amd64.whl

luna_quantum/solve/parameters/algorithms/quantum_gate/vqe.py

@@ -0,0 +1,108 @@
+import math
+from typing import Any, Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params.scipy_optimizer import (
+    ScipyOptimizerParams,
+)
+from luna_quantum.solve.parameters.backends import IBM
+
+
+class VQE(LunaAlgorithm[IBM]):
+    """
+    Parameters for the Variational Quantum Eigensolver (VQE) algorithm.
+
+    VQE is a hybrid quantum-classical algorithm designed to find the ground state energy
+    of a Hamiltonian by variationally optimizing a parameterized quantum circuit.
+    It's widely used in quantum chemistry to compute molecular ground state energies
+    and electronic structure properties.
+
+    Attributes
+    ----------
+    ansatz : Literal["NLocal", "EfficientSU2", "RealAmplitudes", "PauliTwoDesign"]
+        The variational form (parameterized circuit) to use. Default is "EfficientSU2",
+        a hardware-efficient ansatz using SU(2) rotation gates that works well on NISQ
+        devices due to its shallow depth and flexibility.
+    ansatz_config : dict[str, Any]
+        Configuration options for the selected ansatz, such as:
+
+        - entanglement: Pattern of entangling gates ("linear", "full", etc.)
+        - reps: Number of repetitions of the ansatz structure
+        - rotation_blocks: Types of rotation gates to use
+
+        Default is an empty dictionary, using the ansatz's default settings.
+    shots : int | None
+        Number of measurement samples per circuit execution. Higher values improve
+        accuracy by reducing statistical noise at the cost of longer runtime.
+        Default is 1024, which balances accuracy with execution time.
+    optimizer : ScipyOptimizerParams | Dict
+        Configuration for the classical optimization routine that updates the
+        variational parameters. Default is a ScipyOptimizer instance with default
+        settings. See ScipyOptimizer Params class or for details
+        of contained parameters.
+    initial_params_seed: int | None
+        Seed for random number generator for intial params.
+    initial_params_range: tuple[float, float]
+        Range of initial parameter values.
+    """
+
+    ansatz: Literal["NLocal", "EfficientSU2", "RealAmplitudes", "PauliTwoDesign"] = (
+        "EfficientSU2"
+    )
+
+    ansatz_config: dict[str, Any] = Field(default_factory=dict)
+    shots: int | None = 1024  # Number of circuit executions
+
+    optimizer: ScipyOptimizerParams = Field(
+        default_factory=lambda: ScipyOptimizerParams()
+    )
+
+    initial_params_seed: int | None = None
+    initial_params_range: tuple[float, float] = Field(default=(0, 2 * math.pi))
+
+    @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 "VQE"
+
+    @classmethod
+    def get_default_backend(cls) -> IBM:
+        """
+        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 IBM()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[IBM]]:
+        """
+        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 (IBM,)

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

@@ -0,0 +1,5 @@
+from .dialectic_search import DialecticSearch
+from .qbsolv_like_tabu_search import QBSolvLikeTabuSearch
+from .tabu_search import TabuSearch
+
+__all__ = ["DialecticSearch", "QBSolvLikeTabuSearch", "TabuSearch"]

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

@@ -0,0 +1,136 @@
+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 (
+    Decomposer,
+    TabuSearchBaseParams,
+)
+from luna_quantum.solve.parameters.backends import DWave
+from luna_quantum.solve.parameters.constants import DEFAULT_ATOL, DEFAULT_RTOL
+
+
+class DialecticSearch(LunaAlgorithm[DWave]):
+    """
+    Parameters for the Dialectic Search optimization algorithm.
+
+    Dialectic Search is an iterative metaheuristic that uses a
+    thesis-antithesis-synthesis approach to explore the solution space. It starts with
+    a thesis (initial solution) and generates an antithesis (complementary solution).
+    Then it performs a path search between them to synthesize improved solutions, using
+    tabu search for all three phases.
+
+    Attributes
+    ----------
+    antithesis_tabu_params: TabuSearchParams
+        Parameters for the antithesis phase of the search process. The antithesis
+        deliberately explores contrasting regions of the solution space to ensure
+        diversity and avoid getting trapped in local optima. This phase often uses
+        different tabu parameters to promote exploration over exploitation.
+        Default is a TabuSearchParams instance with default settings.
+    synthesis_tabu_params: TabuSearchParams
+        Parameters for the synthesis phase of the search process. The synthesis combines
+        aspects of both thesis and antithesis to generate new candidate solutions,
+        exploring the path between these solutions to find potentially better optima.
+        This phase is critical for discovering high-quality solutions that neither
+        thesis nor antithesis alone would find.
+        Default is a TabuSearchParams instance with default settings.
+    max_iter: int | None
+        Maximum number of iterations for the solver. This limits the total number of
+        dialectic cycles (thesis-antithesis-synthesis) that will be performed.
+        Higher values allow for more thorough exploration 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. 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.
+    max_tries: int | None
+        Maximum number of synthesis attempts for each input state before moving to a new
+        thesis. Controls how persistently the algorithm explores the path between
+        thesis and antithesis before generating new starting points. Higher values
+        allow for more thorough path exploration but may slow progress if paths are
+        unproductive. Default is 100. Must be ≥1.
+    decomposer: Decomposer
+        Decomposer: Breaks down problems into subproblems of manageable size
+        Default is a Decomposer instance with default settings.
+    """
+
+    antithesis_tabu_params: TabuSearchBaseParams = Field(
+        default_factory=TabuSearchBaseParams
+    )
+    synthesis_tabu_params: TabuSearchBaseParams = Field(
+        default_factory=TabuSearchBaseParams
+    )
+
+    decomposer: Decomposer = Field(default_factory=Decomposer)
+    max_iter: int | None = 100
+    max_time: int = 5
+    convergence: int = 3
+    target: float | None = None
+    rtol: float = DEFAULT_RTOL
+    atol: float = DEFAULT_ATOL
+    max_tries: int | None = Field(default=100, ge=1)
+
+    @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 "DS"
+
+    @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/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,)