luna-quantum 1.0.8rc2__cp314-cp314-macosx_10_12_x86_64.whl

luna_quantum/solve/parameters/algorithms/lq_fda/fujits_da_base.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.backends import Fujitsu
+
+
+class FujitsuDABase(LunaAlgorithm[Fujitsu]):
+    """Fujitsu Digital Annealer base parameters.
+
+    Parameters
+    ----------
+    scaling_action: Literal["NOTHING", "SCALING", "AUTO_SCALING"]
+        Method for scaling ``qubo`` and determining temperatures:
+        - "NOTHING": No action (use parameters exactly as specified)
+        - "SCALING": ``scaling_factor`` is multiplied to ``qubo``,
+          ``temperature_start``, ``temperature_end`` and ``offset_increase_rate``.
+        - "AUTO_SCALING": A maximum scaling factor w.r.t. ``scaling_bit_precision``
+          is multiplied to ``qubo``, ``temperature_start``, ``temperature_end`` and
+          ``offset_increase_rate``.
+    scaling_factor: int | float
+        Multiplicative factor applied to model coefficients, temperatures, and other
+        parameters: the ``scaling_factor`` for ``qubo``, ``temperature_start``,
+        ``temperature_end`` and ``offset_increase_rate``.
+        Higher values can improve numerical precision but may lead to overflow.
+        Default is 1.0 (no scaling).
+    scaling_bit_precision: int
+        Maximum bit precision to use when scaling. Determines the maximum allowable
+        coefficient magnitude. Default is 64, using full double precision.
+    random_seed: Union[int, None]
+        Seed for random number generation to ensure reproducible results.
+        Must be between 0 and 9_999. Default is None (random seed).
+    penalty_factor: float
+        Penalty factor used to scale the equality constraint penalty function,
+        default 1.0.
+    inequality_factor: int
+        Penalty factor used to scale the inequality constraints, default 1.
+    remove_ohg_from_penalty: bool
+        If equality constraints, identified to be One-Hot constraints are only
+        considered within one-hot groups (`remove_ohg_from_penalty=True`), i.e.,
+        identified one-hot constraints are not added to the penalty function,
+        default True.
+    """
+
+    scaling_action: Literal["NOTHING", "SCALING", "AUTO_SCALING"] = "NOTHING"
+    scaling_factor: int | float = 1.0
+    scaling_bit_precision: int = 64
+    random_seed: int | None = Field(default=None, ge=0, le=9_999)
+
+    penalty_factor: float = 1.0
+    inequality_factor: int = 1
+    remove_ohg_from_penalty: bool = True
+
+    @classmethod
+    def get_default_backend(cls) -> Fujitsu:
+        """
+        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 Fujitsu()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[Fujitsu], ...]:
+        """
+        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 (Fujitsu,)

luna_quantum/solve/parameters/algorithms/lq_fda/fujitsu_da_v3c.py

@@ -0,0 +1,155 @@
+from pydantic import Field
+
+from .fujits_da_base import FujitsuDABase
+
+
+class FujitsuDA(FujitsuDABase):
+    """
+    Parameters for the Fujitsu Digital Annealer (v3c).
+
+    Attributes
+    ----------
+    time_limit_sec: int | None
+        Maximum running time of DA in seconds. Specifies the upper limit of running
+        time of DA. Time_limit_sec should be selected according to problem hardness
+        and size (number of bits). Min: 1, Max: 3600
+    target_energy: int | None
+        Threshold energy for fast exit. This may not work correctly if the specified
+        value is larger than its max value or lower than its min value.
+        Min: -99_999_999_999, Max: 99_999_999_999
+    num_group: int
+        Number of independent optimization processes. Increasing the number of
+        independent optimization processes leads to better coverage of the search
+        space. Note: Increasing this number requires to also increase time_limit_sec
+        such that the search time for each process is sufficient.
+        Default: 1, Min: 1, Max: 16
+    num_solution: int
+        Number of solutions maintained and updated by each optimization process.
+        Default: 16, Min: 1, Max: 1024
+    num_output_solution: int
+        Maximal number of the best solutions returned by each optimization.
+        Total number of results is ``num_solution`` * ``num_group``.
+        Default: 5, Min: 1, Max: 1024
+    gs_num_iteration_factor: int
+        Maximal number of iterations in one epoch of the global search in each
+        optimization is ``gs_num_iteration_factor`` * *number of bits*.
+        Default: 5, Min: 0, Max: 100
+    gs_num_iteration_cl: int
+        Maximal number of iterations without improvement in one epoch of the global
+        search in each optimization before terminating and continuing with the next
+        epoch. For problems with very deep local minima having a very low value is
+        helpful. Default: 800, Min: 0, Max: 1000000
+    gs_ohs_xw1h_num_iteration_factor: int
+        Maximal number of iterations in one epoch of the global search in each
+        optimization is ``gs_ohs_xw1h_num_iteration_factor`` * *number of bits*.
+        Only used when 1Hot search is defined. Default: 3, Min: 0, Max: 100
+    gs_ohs_xw1h_num_iteration_cl: int
+        Maximal number of iterations without improvement in one epoch of the global
+        search in each optimization before terminating and continuing with the next
+        epoch. For problems with very deep local minima having a very low value is
+        helpful. Only used when 1Hot search is defined.
+        Default: 100, Min: 0, Max: 1000000
+    ohs_xw1h_internal_penalty: int | str
+        Mode of 1hot penalty constraint generation.
+        - 0: internal penalty generation off: 1hot constraint as part of penalty
+             polynomial required
+        - 1: internal penalty generation on: 1hot constraint not as part of penalty
+             polynomial required
+        If 1way 1hot constraint or a 2way 1hot constraint is specified,
+        ``ohs_xw1h_internal_penalty`` = 1 is recommended.
+        Default: 0, Min: 0, Max: 1
+    gs_penalty_auto_mode: int
+        Parameter to choose whether to automatically incrementally adapt
+        ``gs_penalty_coef`` to the optimal value.
+        - 0: Use ``gs_penalty_coef`` as the fixed factor to weight the penalty
+             polynomial during optimization.
+        - 1: Start with ``gs_penalty_coef`` as weight factor for penalty polynomial
+             and automatically and incrementally increase this factor during
+             optimization by multiplying ``gs_penalty_inc_rate`` / 100 repeatedly
+             until ``gs_max_penalty_coef`` is reached or the penalty energy iszero.
+        Default: 1, Min: 0, Max: 1
+    gs_penalty_coef: int
+        Factor to weight the penalty polynomial. If ``gs_penalty_auto_mode`` is 0,
+        this value does not change. If ``gs_penalty_auto_mode`` is 1, this initial
+        weight factor is repeatedly increased by ``gs_penalty_inc_rate`` until
+        ``gs_max_penalty_coef`` is reached or the penalty energy is zero.
+        Default: 1, Min: 1, Max: 9_223_372_036_854_775_807
+    gs_penalty_inc_rate: int
+        Only used if ``gs_penalty_auto_mode`` is 1. In this case, the initial weight
+        factor ``gs_penalty_coef`` for the penalty polynomial is repeatedly
+        increased by multiplying ``gs_penalty_inc_rate`` / 100 until
+        ``gs_max_penalty_coef`` is reached or the penalty energy is zero.
+        Default: 150, Min: 100, Max: 200
+    gs_max_penalty_coef: int
+        Maximal value for the penalty coefficient. If ``gs_penalty_auto_mode`` is 0,
+        this is the maximal value for ``gs_penalty_coef``.
+        If ``gs_penalty_auto_mode`` is 1, this is the maximal value to which
+        ``gs_penalty_coef`` can be increased during the automatic adjustment.
+        If ``gs_max_penalty_coef`` is set to 0, then the maximal penalty coefficient
+        is 2^63 - 1.
+        Default: 0, Min: 0, Max: 9_223_372_036_854_775_807
+
+
+    scaling_action: Literal["NOTHING", "SCALING", "AUTO_SCALING"]
+        Method for scaling ``qubo`` and determining temperatures:
+        - "NOTHING": No action (use parameters exactly as specified)
+        - "SCALING": ``scaling_factor`` is multiplied to ``qubo``,
+          ``temperature_start``, ``temperature_end`` and ``offset_increase_rate``.
+        - "AUTO_SCALING": A maximum scaling factor w.r.t. ``scaling_bit_precision``
+          is multiplied to ``qubo``, ``temperature_start``, ``temperature_end`` and
+          ``offset_increase_rate``.
+    scaling_factor: int | float
+        Multiplicative factor applied to model coefficients, temperatures, and other
+        parameters: the ``scaling_factor`` for ``qubo``, ``temperature_start``,
+        ``temperature_end`` and ``offset_increase_rate``.
+        Higher values can improve numerical precision but may lead to overflow.
+        Default is 1.0 (no scaling).
+    scaling_bit_precision: int
+        Maximum bit precision to use when scaling. Determines the maximum allowable
+        coefficient magnitude. Default is 64, using full double precision.
+    random_seed: Union[int, None]
+        Seed for random number generation to ensure reproducible results.
+        Must be between 0 and 9_999. Default is None (random seed).
+    penalty_factor: float
+        Penalty factor used to scale the equality constraint penalty function,
+        default 1.0.
+    inequality_factor: int
+        Penalty factor used to scale the inequality constraints, default 1.
+    remove_ohg_from_penalty: bool
+        If equality constraints, identified to be One-Hot constraints are only
+        considered within one-hot groups (`remove_ohg_from_penalty=True`),
+        i.e., identified one-hot constraints are not added to the penalty function,
+        default True.
+    """
+
+    time_limit_sec: int | None = Field(default=None, ge=1, le=3600)
+    target_energy: int | None = Field(
+        default=None, ge=-99_999_999_999, le=99_999_999_999
+    )
+    num_group: int = Field(default=1, ge=1, le=16)
+    num_solution: int = Field(default=16, ge=1, le=1024)
+    num_output_solution: int = Field(default=5, ge=1, le=1024)
+    gs_num_iteration_factor: int = Field(default=5, ge=0, le=100)
+    gs_num_iteration_cl: int = Field(default=800, ge=0, le=1_000_000)
+    gs_ohs_xw1h_num_iteration_factor: int = Field(default=3, ge=0, le=100)
+    gs_ohs_xw1h_num_iteration_cl: int = Field(default=100, ge=0, le=1_000_000)
+    ohs_xw1h_internal_penalty: int = Field(default=0, ge=0, le=1)
+    gs_penalty_auto_mode: int = Field(default=1, ge=0, le=1)
+    gs_penalty_coef: int = Field(default=1, ge=1, le=2**63 - 1)
+    gs_penalty_inc_rate: int = Field(default=150, ge=100, le=200)
+    gs_max_penalty_coef: int = Field(default=0, ge=0, le=2**63 - 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 "FDAV3C"

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

@@ -0,0 +1,3 @@
+from .scip import SCIP
+
+__all__ = ["SCIP"]

luna_quantum/solve/parameters/algorithms/optimization_solvers/scip.py

@@ -0,0 +1,51 @@
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.backends.zib import ZIB
+
+
+class SCIP(LunaAlgorithm[ZIB]):
+    """Parameters for the "Solve Constraint Integer Programming" (SCIP) solver."""
+
+    @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 "SCIP"
+
+    @classmethod
+    def get_default_backend(cls) -> ZIB:
+        """
+        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
+        -------
+            BACKEND_TYPE
+                An instance of a class implementing the IBackend interface that serves
+                as the default backend.
+        """
+        return ZIB()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[ZIB], ...]:
+        """
+        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 (ZIB,)

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