luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

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,)

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

@@ -0,0 +1,121 @@
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params import (
+    QuantumAnnealingParams,
+)
+from luna_quantum.solve.parameters.backends import DWaveQpu
+
+
+class QuantumAnnealing(QuantumAnnealingParams, LunaAlgorithm[DWaveQpu]):
+    """
+    Quantum Annealing algorithm for physical quantum processors (QPUs).
+
+    Quantum Annealing is a metaheuristic that leverages quantum effects to find the
+    ground state of a system, corresponding to the optimal solution of an optimization
+    problem.
+
+    The process starts in a quantum superposition of all possible states, and gradually
+    evolves the system according to a time-dependent Hamiltonian, exploiting quantum
+    tunneling to potentially escape local minima more effectively than classical
+    methods.
+
+    This implementation is specifically for D-Wave quantum annealers or similar
+    hardware.
+
+    This class inherits all parameters from QuantumAnnealingParams, providing
+    a complete set of controls for the quantum annealing process on hardware devices.
+
+    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.
+    """
+
+    @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 "QA"
+
+    @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,)