Skip to content

Kerberos

Kerberos divides the problem into subproblems and solves them using Tabu Search, Simulated Annealing and QPU Subproblem Sampling. These algorithms are executed in parallel and afterwards the best solutions are combined. This procedure is applied iteratively until the best solution is found or a termination criterion is met.

Compatible Backends

The Kerberos algorithm supports the following backends:

By default, Kerberos uses the DWaveQpu backend.

Initialization

The following section outlines the default configurations of Kerberos. You can also specify other compatible backends for the algorithm. When backend=None is specified, the default backend will be initialized automatically. In this case, if the backend requires a token, it will be taken from the environment variables.

Default Configuration
from luna_quantum.solve.parameters.algorithms import Kerberos
from luna_quantum.solve.parameters.algorithms.base_params import (
    Decomposer,
    QuantumAnnealingParams,
    SimulatedAnnealingBaseParams,
    TabuKerberosParams
)

algorithm = Kerberos(
    backend=None,
    num_reads=100,
    num_retries=0,
    max_iter=100,
    max_time=5,
    convergence=3,
    target=None,
    rtol=1e-05,
    atol=1e-08,
    simulated_annealing_params=SimulatedAnnealingBaseParams(
        num_reads=None,
        num_sweeps=1000,
        beta_range=None,
        beta_schedule_type='geometric',
        initial_states_generator='random'
    ),
    quantum_annealing_params=QuantumAnnealingParams(
        anneal_offsets=None,
        anneal_schedule=None,
        annealing_time=None,
        auto_scale=None,
        fast_anneal=False,
        flux_biases=None,
        flux_drift_compensation=True,
        h_gain_schedule=None,
        initial_state=None,
        max_answers=None,
        num_reads=1,
        programming_thermalization=None,
        readout_thermalization=None,
        reduce_intersample_correlation=False,
        reinitialize_state=None
    ),
    tabu_kerberos_params=TabuKerberosParams(
        num_reads=None,
        tenure=None,
        timeout=100,
        initial_states_generator='random',
        max_time=None
    ),
    decomposer=Decomposer(
        size=10,
        min_gain=None,
        rolling=True,
        rolling_history=1.0,
        silent_rewind=True,
        traversal='energy'
    )
)

Parameter Details

For a complete overview of available parameters and their usage, see the Kerberos API Reference.

Usage

from luna_quantum import LunaSolve

LunaSolve.authenticate("<YOUR_LUNA_API_KEY>")

# Define your model and algorithm
model = ...
algorithm = ...

solve_job = algorithm.run(model, name="my-solve-job")

API Reference

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:

Name Type Description
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.

atol class-attribute instance-attribute 

atol: float = DEFAULT_ATOL

backend class-attribute instance-attribute 

backend: BACKEND_TYPE | None = Field(default=None, exclude=True, repr=False)

convergence class-attribute instance-attribute 

convergence: int = 3

decomposer class-attribute instance-attribute 

decomposer: Decomposer = Field(default_factory=Decomposer)

max_iter class-attribute instance-attribute 

max_iter: int | None = 100

max_time class-attribute instance-attribute 

max_time: int = 5

model_config class-attribute instance-attribute 

model_config = ConfigDict(
    arbitrary_types_allowed=True, extra="allow", validate_assignment=True
)

num_reads class-attribute instance-attribute 

num_reads: int = 100

num_retries class-attribute instance-attribute 

num_retries: int = 0

quantum_annealing_params class-attribute instance-attribute 

quantum_annealing_params: QuantumAnnealingParams = Field(
    default_factory=QuantumAnnealingParams
)

rtol class-attribute instance-attribute 

rtol: float = DEFAULT_RTOL

simulated_annealing_params class-attribute instance-attribute 

simulated_annealing_params: SimulatedAnnealingBaseParams = Field(
    default_factory=SimulatedAnnealingBaseParams
)

tabu_kerberos_params class-attribute instance-attribute 

tabu_kerberos_params: TabuKerberosParams = Field(
    default_factory=TabuKerberosParams
)

target class-attribute instance-attribute 

target: float | None = None

get_compatible_backends classmethod 

get_compatible_backends() -> tuple[type[DWaveQpu], ...]

Check at runtime if the used backend is compatible with the solver.

Returns:

Type Description
tuple[type[IBackend], ...]

True if the backend is compatible with the solver, False otherwise.

get_default_backend classmethod 

get_default_backend() -> 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:

Type Description
IBackend

An instance of a class implementing the IBackend interface that serves as the default backend.

run 

run(
    model: Model | str,
    name: str | None = None,
    backend: BACKEND_TYPE | None = None,
    client: LunaSolve | str | None = None,
    *args: Any,
    **kwargs: Any,
) -> SolveJob

Run the configured solver.

Parameters:

Name Type Description Default
model Model or str

The model to be optimized or solved. It could be an Model instance or a string identifier representing the model id.

 required
name str | None

If provided, the name of the job. Defaults to None.

 None
backend BACKEND_TYPE | None

Backend to use for the solver. If not provided, the default backend is used.

 None
client LunaSolve or str

The client interface used to interact with the backend services. If not provided, a default client will be used.

 None
*args Any

Additional arguments that will be passed to the solver or client.

 ()
**kwargs Any

Additional keyword parameters for configuration or customization.

 {}

Returns:

Type Description
SolveJob

The job object containing the information about the solve process.