luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

luna_quantum/solve/parameters/algorithms/base_params/scipy_optimizer.py

@@ -0,0 +1,122 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+ScipyOptimizerMethod = Literal[
+    "nelder-mead",
+    "powell",
+    "cg",
+    "bfgs",
+    "newton-cg",
+    "l-bfgs-b",
+    "tnc",
+    "cobyla",
+    "cobyqa",
+    "slsqp",
+    "trust-constr",
+    "dogleg",
+    "trust-ncg",
+    "trust-exact",
+    "trust-krylov",
+    "NELDER-MEAD",
+    "POWELL",
+    "CG",
+    "BFGS",
+    "NEWTON-CG",
+    "L-BFGS-B",
+    "TNC",
+    "COBYLA",
+    "COBYQA",
+    "SLSQP",
+    "TRUST-CONSTR",
+    "DOGLEG",
+    "TRUST-NCG",
+    "TRUST-EXACT",
+    "TRUST-KRYLOV",
+    "Nelder-Mead",
+    "Newton-CG",
+]
+
+
+class ScipyOptimizerParams(BaseModel):
+    """Wrapper for scipy.optimize.minimize.
+
+    See [SciPy minimize documentation](
+    https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html)
+    for more information of the available methods and parameters.
+
+    Attributes
+    ----------
+    method: ScipyOptimizerMethod
+        Type of solver. See
+        [SciPy minimize documentation](
+        https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html)
+        for supported methods.
+    tol: float | None
+        Tolerance for termination.
+    bounds: None | list[tuple[float, float]]
+        Bounds on variables for Nelder-Mead, L-BFGS-B, TNC, SLSQP, Powell,
+        trust-constr, COBYLA, and COBYQA methods. `None` is used to specify no bounds.
+        A sequence of `(min, max)` can be used to specify bounds for each parameter
+        individually.
+    jac: None | Literal["2-point", "3-point", "cs"]
+        Method for computing the gradient vector. Only for CG, BFGS, Newton-CG,
+        L-BFGS-B, TNC, SLSQP, dogleg, trust-ncg, trust-krylov, trust-exact and
+        trust-constr.
+    hess: None | Literal["2-point", "3-point", "cs"]
+        Method for computing the Hessian matrix. Only for Newton-CG, dogleg, trust-ncg,
+        trust-krylov, trust-exact and trust-constr.
+    maxiter: int
+        Maximum number of iterations to perform. Depending on the method
+        each iteration may use several function evaluations. Will be ignored for TNC
+        optimizer. Default: 100
+    options: dict[str, float]
+        A dictionary of solver options.
+    """
+
+    method: ScipyOptimizerMethod = Field(
+        default="cobyla",
+        description="Type of solver. See "
+        "https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html"
+        "for supported methods.",
+    )
+    tol: float | None = Field(
+        default=None, ge=0, description="Tolerance for termination."
+    )
+    bounds: None | list[tuple[float, float]] = Field(
+        default=None,
+        description="Bounds on variables for Nelder-Mead, L-BFGS-B, TNC, SLSQP, Powell,"
+        "trust-constr, COBYLA, and COBYQA methods. None is used to specify no bounds. "
+        "A sequence of `(min, max)` can be used to specify bounds for each parameter "
+        "individually.",
+    )
+    jac: None | Literal["2-point", "3-point", "cs"] = Field(
+        default=None,
+        description="Method for computing the gradient vector. Only for CG, BFGS, "
+        "Newton-CG, L-BFGS-B, TNC, SLSQP, dogleg, trust-ncg, trust-krylov, trust-exact "
+        "and trust-constr.",
+    )
+    hess: None | Literal["2-point", "3-point", "cs"] = Field(
+        default=None,
+        description="Method for computing the Hessian matrix. Only for Newton-CG, "
+        "dogleg, trust-ncg, trust-krylov, trust-exact and trust-constr.",
+    )
+    maxiter: int = Field(
+        default=100,
+        ge=1,
+        le=10000,
+        description="Maximum number of iterations to perform. Depending on the method "
+        "each iteration may use several function evaluations. Will be ignored for TNC "
+        "optimizer.",
+    )
+    options: dict[str, float] = Field(
+        default_factory=dict, description="A dictionary of solver options."
+    )
+
+    @field_validator("options", mode="after")
+    @classmethod
+    def _ensure_no_maxiter(cls, v: dict[str, float]) -> dict[str, float]:
+        if "maxiter" in v:
+            msg = "Please do not specify `maxiter` in options dict."
+            raise ValueError(msg)
+        return v

luna_quantum/solve/parameters/algorithms/base_params/simulated_annealing_params.py

@@ -0,0 +1,106 @@
+from collections.abc import Sequence
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+
+class SimulatedAnnealingBaseParams(BaseModel):
+    """
+    Parameters for the Simulated Annealing optimization algorithm.
+
+    This class extends the basic SimulatedAnnealing parameters with additional controls
+    for more fine-grained customization of the annealing process, allowing advanced
+    users to tune the algorithm for specific problem characteristics.
+
+    Simulated Annealing mimics the physical annealing process where a material is heated
+    and then slowly cooled to remove defects. In optimization, this translates to
+    initially accepting many non-improving moves (high temperature) and gradually
+    becoming more selective (cooling) to converge to an optimum.
+
+    Attributes
+    ----------
+    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.
+    """
+
+    num_reads: int | None = None
+    num_sweeps: int | None = 1_000
+    beta_range: list[float] | tuple[float, float] | None = None
+    beta_schedule_type: Literal["linear", "geometric"] = "geometric"
+    initial_states_generator: Literal["none", "tile", "random"] = "random"
+
+
+class SimulatedAnnealingParams(SimulatedAnnealingBaseParams):
+    """
+    Extended parameters for the Simulated Annealing optimization algorithm.
+
+    This class extends the basic SimulatedAnnealing parameters with additional controls
+    for more fine-grained customization of the annealing process, allowing advanced
+    users to tune the algorithm for specific problem characteristics.
+
+    Simulated Annealing mimics the physical annealing process where a material is heated
+    and then slowly cooled to remove defects. In optimization, this translates to
+    initially accepting many non-improving moves (high temperature) and gradually
+    becoming more selective (cooling) to converge to an optimum.
+
+    Attributes
+    ----------
+    num_sweeps_per_beta: int
+        Number of sweeps to perform at each temperature before cooling. More sweeps
+        per temperature allow better exploration at each temperature level.
+        Default is 1, which works well for many problems.
+    seed: Optional[int]
+        Random seed for reproducible results. Using the same seed with identical
+        parameters produces identical results. Default is None (random seed).
+    beta_schedule: Sequence[float] | None
+        Explicit sequence of beta (inverse temperature) values to use. Provides complete
+        control over the cooling schedule. Format must be compatible with numpy.array.
+        Default is None, which generates a schedule based on beta_range and
+        beta_schedule_type.
+    initial_states: Optional[Any]
+        One or more starting states, each defining values for all problem variables.
+        This allows the algorithm to start from promising regions rather than random
+        points.
+        Default is None (random starting states).
+    randomize_order: bool
+        When True, variables are updated in random order during each sweep.
+        When False, variables are updated sequentially. Random updates preserve
+        symmetry of the model but are slightly slower. Default is False for efficiency.
+    proposal_acceptance_criteria: Literal["Gibbs", "Metropolis"]
+        Method for accepting or rejecting proposed moves:
+        - "Gibbs": Samples directly from conditional probability distribution
+        - "Metropolis": Uses Metropolis-Hastings rule (accept if improving, otherwise
+          accept with probability based on energy difference and temperature)
+        Default is "Metropolis", which is typically faster and works well for most
+        problems.
+    """
+
+    num_sweeps_per_beta: int = 1
+    seed: int | None = None
+    beta_schedule: Sequence[float] | None = None
+    initial_states: Any | None = None
+    randomize_order: bool = False
+    proposal_acceptance_criteria: Literal["Gibbs", "Metropolis"] = "Metropolis"

luna_quantum/solve/parameters/algorithms/base_params/tabu_kerberos_params.py

@@ -0,0 +1,39 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class TabuKerberosParams(BaseModel):
+    """
+    Mixin class that provides parameters for TabuKerberos algorithm.
+
+    TabuKerberos implements a specialized version of TabuSearch with time-based
+    constraints. This mixin provides the parameters needed to configure the
+    tabu search component.
+
+    Attributes
+    ----------
+    num_reads: Optional[int]
+        Number of reads. Each read is generated by one run of the tabu algorithm.
+        Default is None, which matches the number of initial states or uses one
+        if no initial states are provided.
+    tenure: Optional[int]
+        Tabu tenure, which is the length of the tabu list, or number of recently
+        explored solutions kept in memory. Default is None (a quarter of the
+        number of problem variables up to a maximum value of 20).
+    timeout: float
+        Maximum running time per read in milliseconds. Default is 100.
+    initial_states_generator: Literal['none', 'tile', 'random']
+        Defines the expansion of `initial_states` if fewer than `num_reads` are
+        specified. Default is "random".
+    max_time: float | None
+        Overall maximum duration in seconds for the entire tabu search algorithm.
+        Default is None (run until convergence criteria are met).
+    """
+
+    num_reads: int | None = None
+    tenure: int | None = Field(default=None, le=20)
+    timeout: float = 100
+    initial_states_generator: Literal["none", "tile", "random"] = "random"
+
+    max_time: float | None = None

luna_quantum/solve/parameters/algorithms/base_params/tabu_search_params.py

@@ -0,0 +1,129 @@
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class TabuSearchBaseParams(BaseModel):
+    """
+    Parameters for the Tabu Problem 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
+    ----------
+    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.
+    """
+
+    num_reads: int | None = None
+    tenure: int | None = Field(default=None, le=20)
+    timeout: float = 100
+
+
+class TabuSearchParams(TabuSearchBaseParams):
+    """
+    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.
+    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.
+    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).
+    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.
+    """
+
+    seed: int | None = None
+    num_restarts: int = 1_000_000
+    energy_threshold: float | None = None
+    coefficient_z_first: int | None = None
+    coefficient_z_restart: int | None = None
+    lower_bound_z: int | None = None
+
+    initial_states: Any | None = None
+    initial_states_generator: Literal["none", "tile", "random"] = "random"

luna_quantum/solve/parameters/algorithms/flexible_parameter_algorithm.py

@@ -0,0 +1,59 @@
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract.luna_algorithm import LunaAlgorithm
+from luna_quantum.solve.interfaces.backend_i import IBackend
+from luna_quantum.solve.parameters.backends.dwave import DWave
+
+
+class FlexibleParameterAlgorithm(LunaAlgorithm[IBackend]):
+    """Define an algorithm with flexible parameter.
+
+    This class is used to represent algorithms with flexible parameters designed
+    to work with a specific backend system. It also provides methods to interact
+    with default and compatible backends.
+    """
+
+    luna_algorithm_name: str = Field(
+        ..., exclude=True, repr=False, alias="algorithm_name"
+    )
+
+    @property
+    def algorithm_name(self) -> str:
+        """
+        Get the name of the algorithm.
+
+        Returns
+        -------
+        str
+            The name of the algorithm used.
+        """
+        return self.luna_algorithm_name
+
+    @classmethod
+    def get_default_backend(cls) -> DWave:
+        """
+        Get the default backend for computations.
+
+        The method returns a default instance of the DWave class, which can
+        be used as a backend for computations.
+
+        Returns
+        -------
+        DWave
+            An instance of the DWave class.
+        """
+        return DWave()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[IBackend], ...]:
+        """
+        Get compatible backend classes.
+
+        Return a tuple of backend types that are compatible with the current class.
+
+        Returns
+        -------
+        tuple of type[IBackend, ...]
+            Tuple containing classes of compatible backends.
+        """
+        return (IBackend,)

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

@@ -0,0 +1,4 @@
+from .qaga import QAGA
+from .saga import SAGA
+
+__all__ = ["QAGA", "SAGA"]

luna_quantum/solve/parameters/algorithms/genetic_algorithms/qaga.py

@@ -0,0 +1,131 @@
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.backends import DWaveQpu
+from luna_quantum.solve.parameters.constants import DEFAULT_ATOL, DEFAULT_RTOL
+
+
+class QAGA(LunaAlgorithm[DWaveQpu]):
+    """
+    Parameters for the Quantum Assisted Genetic Algorithm (QAGA).
+
+    QAGA combines quantum computing with genetic algorithms to enhance the search for
+    optimal solutions. It uses quantum annealing for mutation and recombination
+    operations, potentially allowing the algorithm to escape local optima more
+    effectively than classical genetic algorithms.
+
+    The algorithm maintains a population of candidate solutions that evolve through
+    selection, quantum-enhanced recombination, and mutation operations across
+    generations.
+
+    Attributes
+    ----------
+    p_size : int
+        Initial population size (number of candidate solutions). Larger populations
+        provide more diversity but require more computation. Default is 20, suitable
+        for small to medium problems.
+    p_inc_num : int
+        Number of new individuals added to the population after each generation.
+        Controls population growth rate. Default is 5, allowing moderate expansion.
+    p_max : int | None
+        Maximum population size. Once reached, no more growth occurs. Prevents
+        unbounded population expansion. Default is 160, balancing diversity with
+        computational cost.
+    pct_random_states : float
+        Percentage of random states added to the population after each iteration.
+        Helps maintain diversity and avoid premature convergence. Default is 0.25 (25%).
+    mut_rate : float
+        Mutation rate - probability to mutate an individual after each iteration.
+        Higher values favor exploration, lower values favor exploitation.
+        Default is 0.5, balanced between the two. Must be between 0.0 and 1.0.
+    rec_rate : int
+        Recombination rate - number of mates each individual is recombined with
+        per generation. Higher values increase genetic mixing. Default is 1.
+    rec_method : Literal["cluster_moves", "one_point_crossover", "random_crossover"]
+        Method used for recombining individuals:
+        - "cluster_moves": Swaps clusters of related variables between solutions
+        - "one_point_crossover": Splits solutions at a random point and exchanges parts
+        - "random_crossover": Randomly exchanges bits between parents
+        Default is "random_crossover", which provides good exploration.
+    select_method : Literal["simple", "shared_energy"]
+        Selection strategy for the next generation:
+        - "simple": Pure energy-based selection
+        - "shared_energy": Promotes diversity by penalizing similar solutions
+        Default is "simple", focusing on solution quality.
+    target : float | None
+        Target energy level to stop the algorithm. If None, runs until other criteria
+        are met. Default is None.
+    atol : float
+        Absolute tolerance when comparing energies to target. Default is 0.0.
+    rtol : float
+        Relative tolerance when comparing energies to target. Default is 0.0.
+    timeout : float
+        Maximum runtime in seconds. Includes preprocessing, network overhead, and
+        quantum processing time. Default is 60.0 seconds.
+    max_iter : Union[int, None]
+        Maximum number of generations before stopping. None means no limit.
+        Default is 100 generations.
+    """
+
+    p_size: int = 20
+    p_inc_num: int = 5
+    p_max: int | None = 160
+    pct_random_states: float = 0.25
+    mut_rate: float = Field(default=0.5, ge=0.0, le=1.0)
+    rec_rate: int = 1
+    rec_method: Literal["cluster_moves", "one_point_crossover", "random_crossover"] = (
+        "random_crossover"
+    )
+    select_method: Literal["simple", "shared_energy"] = "simple"
+    target: float | None = None
+    atol: float = DEFAULT_ATOL
+    rtol: float = DEFAULT_RTOL
+    timeout: float = 60.0
+    max_iter: int | None = 100
+
+    @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 "QAGA+"
+
+    @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,)