Bases: LunaAlgorithm[AWS | IonQ | IQM | Rigetti | IBMQuantum | AerSimulator | IBMFakeBackend | CudaqCpu | CudaqGpu]

Quantum Approximate Optimization Algorithm (QAOA).

QAOA is a hybrid quantum-classical algorithm for solving combinatorial optimization problems. It works by preparing a quantum state through alternating applications of problem-specific (cost) and mixing Hamiltonians, controlled by variational parameters that are optimized classically to maximize the probability of measuring the optimal solution.

QAOA is particularly suited for problems that can be encoded as quadratic unconstrained binary optimization (QUBO) or Ising models, such as MaxCut, TSP, and portfolio optimization.

Attributes:

• reps (int) –

  Number of QAOA layers (p). Each layer consists of applying both the cost and mixing Hamiltonians with different variational parameters. Higher values generally lead to better solutions but increase circuit depth and quantum resources required. Default is 1.

• shots (int) –

  Number of measurement samples to collect per circuit execution. Higher values reduce statistical noise but increase runtime. Default is 1024.

• optimizer (ScipyOptimizerParams) –

  Configuration for the classical optimization routine that updates the variational parameters. Default is a ScipyOptimizer instance with default settings. See ScipyOptimizerParams class for details of contained parameters.

• initial_params (LinearQAOAParams | BasicQAOAParams | RandomQAOAParams) –

  Custom QAOA variational circuit parameters. By default linear increasing/decreasing parameters for the selected reps are generated.

Bases: LunaAlgorithm[Qctrl]

Quantum Approximate Optimization Algorithm via Fire Opal (QAOA_FO).

QAOA_FO is Q-CTRL's implementation of the Quantum Approximate Optimization Algorithm (QAOA) through their Fire Opal framework. It is a hybrid quantum-classical algorithm for solving combinatorial optimization problems with enhanced performance through Q-CTRL's error mitigation and control techniques. For more details, please refer to the Fire Opal QAOA documentation <https://docs.q-ctrl.com/fire-opal/execute/run-algorithms/solve-optimization-problems/fire-opals-qaoa-solver>_.

The algorithm works by preparing a quantum state through alternating applications of problem-specific (cost) and mixing Hamiltonians, controlled by variational parameters that are optimized classically to maximize the probability of measuring the optimal solution.

QAOA_FO leverages Q-CTRL's expertise in quantum control to improve circuit fidelity and optimization performance. It is particularly suited for problems that can be encoded as quadratic unconstrained binary optimization (QUBO) or Ising models, such as MaxCut, TSP, and portfolio optimization.

Bases: LunaAlgorithm[Aqarios | AqariosGpu | AerSimulator | IBMFakeBackend | IBMQuantum], BaseModel

The FlexQAOA algorithm for constrained quantum optimization.

The FlexQAOA is an extension to the default QAOA with the capabilities to encode inequality constriants with indicator functions as well as one-hot constraints through XY-mixers. This algorithm will dynamically extract all constraints from the given constraint input optimization model, and construct an accoring QAOA circuit. Currently only simulation of the circuit is supported. But due to the constrained nature, the subspace of the Hilbertspace required for simulation is smaller, depending on the problem instance. This allows for simulation of problems with more qubits than ordinary state vector simulation allows. For now, the simulation size is limited to Hilbertspaces with less <= 2**18 dimensions.

The FlexQAOA allows for a dynamic circuit construction depending on input paramters. Central to this is the pipeline parameter which allows for different configurations.

For instance, if one likes to explore ordinary QUBO simulation with all constraints represented as quadratic penalties, the xy_mixers and indicator_function options need to be manually disabled

pipeline.xy_mixer.enable = False
pipeline.indicator_function.enable = False

Following the standard protocol for QAOA, a classical optimizer is required that tunes the variational parameters of the circuit. Besides the classical ScipyOptimizer other optimizers are also featured, allowing for optimizing only a linear schedule, starting with optimizing for a linear schedule followed by individual parameter fine tuning, and interpolating between different QAOA circuit depts.

Attributes:

• shots (int) –

  Number of sampled shots.

• reps (int) –

  Number of QAOA layer repetitions

• pipeline (PipelineParams) –

  The pipeline defines the selected features for QAOA circuit generation. By default, all supported features are enabled (one-hot constraints, inequality constraints and quadratic penalties).

• optimizer (ScipyOptimizerParams | CombinedOptimizerParams | InterpolateOptimizerParams | None) –

  The classical optimizer for parameter tuning. Setting to None disables the optimization, leading to an evaluation of the initial parameters.

• initial_params (LinearQAOAParams | BasicQAOAParams | RandomQAOAParams | Dict) –

  Custom QAOA variational circuit parameters. By default linear increasing/decreasing parameters for the selected reps are generated.

• param_conversion (None | Literal["basic"] = "basic") –

  Parameter conversion after initialization. This option set to None means the parameters, as specified are used. This parameter set to "basic" means the parameters are converted to basic parameters before optimization. This is useful if one only wants to optimize the linear schedule of parameters: Then the option None needs to be selected alongside LinearQAOAParams. This option is ignored when CombinedOptimizer is also selected.

• custom_config (CustomConfig) –

  Additional options for the FlexQAOA circuit.

Bases: LunaAlgorithm[IBMQuantum | IBMFakeBackend | AerSimulator]

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.

Bases: 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.

Bases: 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.

Bases: LunaAlgorithm[DWaveQpu]

Parameters for the Repeated Reverse Quantum Annealing algorithm.

This approach combines reverse annealing (starting from a classical state) with repetition to refine solutions iteratively. It's particularly useful for: 1. Local refinement of solutions found by classical methods 2. Escaping local minima by temporarily increasing quantum fluctuations 3. Improving solutions through multiple rounds of quantum optimization

The process involves: - Starting with classical initial states - Partially "unsolving" them by increasing quantum fluctuations - Re-annealing to find potentially better nearby solutions - Repeating with the best solutions found

Attributes:

• anneal_offsets (Any | None) –

  Per-qubit time offsets for the annealing path, allowing qubits to anneal at different rates. Useful for problems with varying energy scales or when certain qubits need different annealing trajectories. Default is None, which uses standard annealing for all qubits.

• annealing_time (Any | None) –

  Duration of the annealing process in microseconds. Longer times can improve solution quality for problems with small energy gaps but increase runtime. Default is None, which uses the QPU's default annealing time.

• auto_scale (Any | None) –

  Whether to automatically normalize the problem energy range to match hardware capabilities, preventing precision issues in the physical implementation. Default is None, which uses the D-Wave system's default setting.

• flux_biases (Any | None) –

  Custom flux bias offsets for each qubit to compensate for manufacturing variations in the QPU hardware or to intentionally bias certain qubits. Default is None, using standard calibration values.

• flux_drift_compensation (bool) –

  Whether to compensate for drift in qubit flux over time, improving the reliability and consistency of results across multiple runs. Default is True, which is recommended for most applications.

• h_gain_schedule (Any | None) –

  Schedule for h-gain (linear coefficient strength) during annealing, allowing dynamic adjustment of problem coefficients throughout the process. Default is None, using standard gain settings.

• max_answers (int | None) –

  Maximum number of unique answer states to return from the quantum hardware. Useful for collecting diverse solutions while filtering out duplicates. Must be greater than or equal to 1 if specified. Default is None, which returns all unique solutions found.

• programming_thermalization (float | None) –

  Wait time (in microseconds) after programming the QPU, allowing it to reach thermal equilibrium before starting the annealing process. Must be positive if specified. Default is None, using system default.

• readout_thermalization (float | None) –

  Wait time (in microseconds) after each anneal before reading results. Helps ensure the qubits have settled into their final states before measurement. Must be positive if specified. Default is None, using system default.

• reduce_intersample_correlation (bool) –

  Whether to add delay between samples to reduce temporal correlations that might bias results across multiple runs. Default is False to minimize runtime, but can be set to True when sample independence is critical.

• initial_states (list[dict[str, int]] | None) –

  Initial classical states to start the reverse annealing from, specified as dictionaries mapping variable names to binary values (0 or 1). For each state, one call to the sampler with parameter initial_state=state will be made in the first iteration. Default is None, in which case random or specified states are generated according to n_initial_states.

• n_initial_states (int) –

  Number of initial states to create when initial_states is None. Controls the diversity of starting points for the algorithm. Ignored if initial_states is provided. Default is 1. Must be ≥1.

• samples_per_state (int) –

  How many samples to create per state in each iteration after the first. More samples increase the chance of finding improvements but use more QPU time. Controls the breadth of exploration around each promising solution. Default is 1. Must be ≥1.

• beta_schedule (list[float]) –

  Beta schedule controlling the quantum fluctuation strength during reverse annealing. Beta is the inverse temperature (1/T), with lower values allowing more thermal excitation to explore the energy landscape more widely. Default [0.5, 3] provides moderate initial fluctuation followed by cooling, balancing exploration and exploitation.

• timeout (float) –

  Maximum runtime in seconds before the solver stops, regardless of convergence. Provides a hard time limit to ensure the algorithm completes within a reasonable timeframe. Default is 300 seconds (5 minutes), balancing solution quality with timeliness.

• max_iter (int) –

  Maximum number of iterations (reverse annealing cycles) to perform. Each iteration refines the solutions from the previous round, potentially discovering better solutions in the neighborhood of good candidates. Default is 10, providing good refinement without excessive QPU usage.

• target (Any | None) –

  Target energy value that, if reached, causes the algorithm to terminate early. Allows for early stopping when a sufficiently good solution is found. Default is None (run until other stopping criteria are met).

• check_trivial (bool) –

  Whether to check for and handle trivial variables (those without interactions) before sending the problem to the QPU. Adds some computational overhead but prevents potential runtime errors and improves embedding efficiency. Default is True, which is recommended for robust operation.

Bases: 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.

Bases: 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.

Bases: 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.

Bases: 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).

Bases: 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.

Bases: SimulatedAnnealingParams, LunaAlgorithm[DWave]

Simulated Annealing optimization algorithm.

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.

This class inherits all parameters from SimulatedAnnealingParams, providing a complete set of controls for fine-grained customization of the annealing process.

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_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.

Bases: 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.

Bases: LunaAlgorithm[DWave]

Parameters for the Population Annealing algorithm.

Population Annealing uses a sequential Monte Carlo method to minimize the energy of a population. The population consists of walkers that can explore their neighborhood during the cooling process. Afterwards, walkers are removed and duplicated using bias to lower energy. Eventually, a population collapse occurs where all walkers are in the lowest energy state.

Attributes:

• max_iter (int) –

  Maximum number of annealing iterations (temperature steps) to perform. Each iteration involves lowering the temperature, allowing walkers to explore locally, and then resampling the population based on Boltzmann weights. Higher values allow for a more gradual cooling schedule, potentially finding better solutions but increasing computation time. Default is 20, which provides a reasonable balance for most problems.

• max_time (int) –

  Maximum time in seconds that the algorithm is allowed to run. Provides a hard time limit regardless of convergence or iteration status. Useful for time-constrained scenarios where some solution is needed within a specific timeframe. Default is 2, which is relatively aggressive and may need to be increased for complex problems.

• fixed_temp_sampler_num_sweeps (int) –

  Number of Monte Carlo sweeps to perform at each temperature level, where one sweep attempts to update all variables once. More sweeps allow walkers to explore their local configuration space more thoroughly, producing better equilibrated samples but increasing computation time. This parameter directly affects how well each walker samples its local energy landscape before resampling occurs. Default is 10,000, which is suitable for thorough exploration of moderate-sized problems.

• fixed_temp_sampler_num_reads (int | None) –

  Number of independent sampling runs to perform at each temperature level. Each run effectively initializes a separate walker in the population. Multiple reads provide better coverage of the solution space, increasing the diversity of the initial population and improving the chances of finding the global optimum. Default is None, which typically defaults to 1 or matches the number

Bases: LunaAlgorithm[DWave], QBSolvLikeMixin

QBSolv Like Simulated Annealing solver.

QBSolv Like Simulated Annealing breaks down the problem and solves the parts individually using a classic solver that uses Simulated Annealing. This particular implementation uses hybrid.SimulatedAnnealingSubproblemSampler (https://docs.ocean.dwavesys.com/projects/hybrid/en/stable/reference/samplers.html#simulatedannealingsubproblemsampler) as a sampler for the subproblems to achieve a QBSolv like behaviour.

This class combines parameters from multiple sources: - QBSolvLikeMixin: Provides parameters for the QBSolv-like decomposition approach - SimulatedAnnealingParams: Provides parameters specific to simulated annealing

Attributes:

• decomposer_size (int) –

  Size for the decomposer, which determines the maximum subproblem size to be handled in each iteration. Larger values may produce better solutions but increase computational complexity exponentially. Default is 50, which balances solution quality with reasonable runtime.

• rolling (bool) –

  Whether to use rolling window decomposition for the solver. When enabled, this allows for overlapping subproblems with shared variables, which can improve solution quality by better handling interactions across subproblem boundaries. Default is True.

• rolling_history (float) –

  Rolling history factor controlling how much of previous subproblem solutions are considered when solving subsequent subproblems. Higher values incorporate more historical information but may slow convergence to new solutions. Default is 0.15 (15% retention).

• max_iter (int | None) –

  Maximum number of iterations (decomposition and solving cycles) to perform. Higher values allow for more thorough optimization but increase runtime. Default is 100.

• max_time (int) –

  Time in seconds after which the algorithm will stop, regardless of convergence status. Provides a hard time limit for time-constrained applications. Default is 5.

• convergence (int) –

  Number of iterations with unchanged output to terminate algorithm. Higher values ensure more stable solutions but may increase computation time unnecessarily if the algorithm has already found the best solution. Default is 3.

• target (float | None) –

  Energy level that the algorithm tries to reach. If this target energy is achieved, the algorithm will terminate early. Default is None, meaning the algorithm will run until other stopping criteria are met.

• rtol (float) –

  Relative tolerance for convergence. Used when comparing energy values between iterations to determine if significant improvement has occurred. Default uses DEFAULT_RTOL.

• atol (float) –

  Absolute tolerance for convergence. Used alongside rtol when comparing energy values to determine if the algorithm has converged. Default uses DEFAULT_ATOL.

• num_reads (Union[int, None]) –

  Number of independent runs of the algorithm, each producing one solution sample. Multiple reads with different random starting points increase the chance of finding the global optimum. Default is None, which matches the number of initial states (or just one read if no initial states are provided).

• num_sweeps (Union[int, None]) –

  Number of iterations/sweeps per run, where each sweep updates all variables once. More sweeps allow more thorough exploration but increase runtime. Default is 1,000, suitable for small to medium problems.

• beta_range (Union[List[float], Tuple[float, float], None]) –

  The inverse temperature (β=1/T) schedule endpoints, specified as [start, end]. A wider range allows more exploration. Default is calculated based on the problem's energy scale to ensure appropriate acceptance probabilities.

• beta_schedule_type (Literal['linear', 'geometric']) –

  How beta values change between endpoints: - "linear": Equal steps (β₁, β₂, ...) - smoother transitions - "geometric": Multiplicative steps (β₁, r·β₁, r²·β₁, ...) - spends more time at lower temperatures for fine-tuning Default is "geometric", which often performs better for optimization problems.

• initial_states_generator (Literal['none', 'tile', 'random']) –

  How to handle cases with fewer initial states than num_reads: - "none": Raises error if insufficient initial states - "tile": Reuses provided states by cycling through them - "random": Generates additional random states as needed Default is "random", which maximizes exploration.

Bases: SimulatedAnnealingParams, LunaAlgorithm[DWave]

Parameters for the Repeated Reverse Simulated Annealing solver.

This algorithm applies principles similar to quantum reverse annealing but in a classical context. It starts from specified states, partially "reverses" the annealing by increasing temperature to explore nearby states, then re-anneals to find improved solutions. This process repeats for multiple iterations, refining solutions progressively.

The approach is particularly effective for problems with complex energy landscapes where standard simulated annealing might get trapped in local optima.

Attributes:

• num_reads_per_iter (list[int] | None) –

  Number of reads (independent runs) to perform in each iteration. Uses num_reads_per_iter[i] in iteration i, and num_reads_per_iter[-1] once the list is exhausted. If None, uses the num_reads value inherited from SimulatedAnnealingParams. This allows dynamic control of sampling intensity across iterations, typically starting with broader exploration and focusing on refinement in later iterations. Minimum list length: 1. Default is None.

• initial_states (Any | None) –

  Starting states for the first iteration. Each state defines values for all problem variables and serves as a starting point for the reverse annealing process. If fewer states than reads are provided, additional states are generated according to the initial_states_generator setting inherited from SimulatedAnnealingParams. Providing good initial states (e.g., from classical heuristics) can significantly improve solution quality. Default is None, which generates random initial states.

• timeout (float) –

  Maximum runtime in seconds before termination, regardless of other stopping criteria. Provides a hard time limit for time-constrained applications. Default is 5.0 seconds, which is suitable for small to medium-sized problems. For larger or more complex problems, consider increasing this value.

• max_iter (int) –

  Maximum number of reverse annealing iterations to perform. Each iteration involves: starting from the best states found so far, raising temperature to explore nearby configurations, then gradually cooling to refine solutions. More iterations generally improve solution quality but increase runtime. Default is 10, providing a good balance for most problems.

• target (Any | None) –

  Target energy value that triggers early termination if reached. Allows the algorithm to stop when a solution of sufficient quality is found, even before reaching max_iter or timeout. Default is None, which means the algorithm will run until other stopping criteria are met.

• 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_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.

Bases: 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.

Bases: LunaAlgorithm[DWave]

Simulated Annealing Genetic Algorithm (SAGA).

SAGA combines genetic algorithms with simulated annealing to enhance optimization. While QAGA uses quantum annealing, SAGA uses classical simulated annealing for the mutation and recombination operations, making it more accessible while still providing benefits over standard genetic algorithms.

The algorithm maintains a population of solutions that evolve through selection, annealing-enhanced recombination, and mutation operations across generations.

Attributes:

• p_size (int) –

  Initial population size (number of candidate solutions). Default is 20.

• p_inc_num (int) –

  Number of new individuals added to the population after each generation. Default is 5.

• p_max (int | None) –

  Maximum population size. Once reached, no more growth occurs. Default is 160.

• pct_random_states (float) –

  Percentage of random states added to the population after each iteration. Default is 0.25 (25%).

• mut_rate (float) –

  Mutation rate - probability to mutate an individual after each iteration. Default is 0.5. Must be between 0.0 and 1.0.

• rec_rate (int) –

  Recombination rate - number of mates each individual is recombined with per generation. Default is 1.

• rec_method (Literal['cluster_moves', 'one_point_crossover', 'random_crossover']) –

  Method used for recombining individuals. Default is "random_crossover".

• select_method (Literal['simple', 'shared_energy']) –

  Selection strategy for the next generation. Default is "simple".

• target (Union[float, None]) –

  Target energy level to stop the algorithm. Default is None.

• atol (float) –

  Absolute tolerance when comparing energies to target. Default is DEFAULT_ATOL.

• rtol (float) –

  Relative tolerance when comparing energies to target. Default is DEFAULT_RTOL.

• timeout (float) –

  Maximum runtime in seconds. Default is 60.0 seconds.

• max_iter (int | None) –

  Maximum number of generations before stopping. Default is 100.

• num_sweeps (int) –

  Initial number of sweeps for simulated annealing in the first iteration. Default is 10.

• num_sweeps_inc_factor (float) –

  Factor by which to increase num_sweeps after each iteration. Default is 1.2 (20% increase per iteration).

• num_sweeps_inc_max (Optional[int]) –

  Maximum number of sweeps that may be reached when increasing the num_sweeps. Default is 7,000.

• beta_range_type (Literal['default', 'percent', 'fixed', 'inc']) –

  Method used to compute the temperature range (beta range) for annealing. Default is "default".

• beta_range (Optional[Tuple[float, float]]) –

  Explicit beta range (inverse temperature) used with beta_range_type "fixed" or "percent". Default is None.

Bases: 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.

Bases: 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.

Bases: 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.

Bases: LunaAlgorithm[ZIB]

Parameters for the "Solve Constraint Integer Programming" (SCIP) solver.