Configs

ClassicalConfig

Bases: Config

A ClassicalConfig instance defines the classical part of a SolverConfig.

ATTRIBUTE	DESCRIPTION
classical_solver_type	Classical solver type. Defaults to "simulated_annealing_tabu_search". TYPE: str | ClassicalSolverType
cplex_maxtime	CPLEX maximum runtime. Defaults to 600s. TYPE: float
cplex_log_path	CPLEX log path. Default to solver.log. TYPE: str
max_iter	Maximum number of iterations to perform for simulated annealing or tabu search. TYPE: int
max_bitstrings	Maximal number of bitstrings returned as solutions. TYPE: int
sa_initial_temp	Starting temperature (controls exploration). TYPE: float
sa_final_temp	Minimum temperature threshold for stopping. TYPE: float
sa_cooling_rate	Cooling rate - should be slightly below 1 (e.g., 0.95–0.99). TYPE: float
sa_seed	Random seed for reproducibility. TYPE: int
sa_start	Optional initial bitstring of shape (n,). TYPE: Tensor | None
sa_energy_tol	Energy tolerance for considering two solutions as equivalent. TYPE: float
sa_time_limit	Maximum runtime in seconds for simulated annealing. Defaults to float('inf'), meaning no time limit. TYPE: float
tabu_x0	The initial binary solution tensor of shape (n,). TYPE: Tensor | None
tabu_tenure	Number of iterations a move (bit flip) remains tabu. TYPE: int
tabu_max_no_improve	Maximum number of consecutive iterations without improvement before termination. TYPE: int
tabu_time_limit	Maximum execution time for tabu search, in seconds. Defaults to float("inf"). TYPE: float

Config

Bases: BaseModel, ABC

Pydantic class for configs.

DecompositionConfig

Bases: Config

The configuration parameters when using a decomposition method for solving large QUBO instances.

ATTRIBUTE	DESCRIPTION
decompose_threshold	Threshold value for cost function used when searching to place a node/variable during decomposition. TYPE: float
decompose_stop_number	Maximal number of nodes/variables left after the decomposition loop. TYPE: int
decompose_break_placement	If a search iteration ends with very few nodes to place/variables on device, we stop iterating. TYPE: int
neglecting_inter_distance	Value for neglecting interactions in the distance interaction matrix. TYPE: float
neglecting_max_coefficient	Qubo coefficient from which we consider an interaction is neglecting. TYPE: float

DriveShapingConfig

Bases: Config

A DriveShapingConfig instance defines the drive shaping part of a SolverConfig.

ATTRIBUTE	DESCRIPTION
drive_shaping_method	Drive shaping method used. Defaults to DriveType.HEURISTIC. TYPE: str | DriveType | type[BaseDriveShaper]
dmm	Whether to use a detuning map when applying drive shaping or not. This adds WeightedDetuning with a Constant Waveform. Defaults to True, which applies DMM. TYPE: bool
optimized_re_execute_opt_drive	Whether to re-run the optimal drive sequence after optimization. Defaults to False. TYPE: bool
optimized_n_calls	Number of calls for the optimization process. Defaults to 20. Note the optimizer accepts a minimal value of 12. TYPE: int
optimized_initial_omega_parameters	Default initial omega parameters for the drive. Defaults to Omega = (1, 2, 1). TYPE: List[float]
optimized_initial_detuning_parameters	Default initial detuning parameters for the drive. Defaults to delta = (-2, 0, 2). TYPE: List[float]
optimized_custom_qubo_cost	Apply a different qubo cost evaluation than the default QUBO evaluation defined in qubosolver/pipeline/drive.py:OptimizedDriveShaper.compute_qubo_cost. Must be defined as: def optimized_custom_qubo_cost(bitstring: str, QUBO: torch.Tensor) -> float. Defaults to None, meaning we use the default QUBO evaluation. TYPE: Callable[[str, Tensor], float]
optimized_custom_objective_fn	For bayesian optimization, one can change the output of qubosolver/pipeline/drive.py:OptimizedDriveShaper.run_simulation to optimize differently. Instead of using the best cost out of the samples, one can change the objective for an average, or any function out of the form cost_eval = optimized_custom_objective_fn(bitstrings, counts, probabilities, costs, best_cost, best_bitstring) Defaults to None, which means we optimize using the best cost out of the samples. TYPE: Callable[[list, list, list, list, float, str], float]
optimized_callback_objective	Apply a callback during bayesian optimization. Only accepts one input dictionary created during optimization d = {"x": x, "cost_eval": cost_eval} hence should be defined as: def callback_fn(d: dict) -> None: Defaults to None, which means no callback is applied. TYPE: Callable[..., None]
optimized_seed	Random seed for the Bayesian optimiser. Defaults to None. TYPE: int | None
heuristic_kappa	Scaling coefficient for the Omega waveform in the heuristic drive shaper. Defaults to 0.25. TYPE: float

EmbeddingConfig

Bases: Config

A EmbeddingConfig instance defines the embedding part of a SolverConfig.

ATTRIBUTE	DESCRIPTION
embedding_method	The type of embedding method used to place atoms on the register according to the QUBO problem. Defaults to EmbedderType.GREEDY. TYPE: str | EmbedderType | type[BaseEmbedder]
greedy_layout	Layout type for the greedy embedder method. Defaults to LayoutType.TRIANGULAR. TYPE: LayoutType | str
greedy_traps	The number of traps on the register. Defaults to -1, i.e. automatically set to match the selected device capacity. A too high value will impede computational efficiency. TYPE: int
greedy_spacing	The minimum distance between atoms. Defaults to 7 (μm). TYPE: float
greedy_density	The estimated density of the QUBO matrix. Defaults to None. TYPE: float
blade_steps_per_round	See Qoolqit's documentation (external) TYPE: int | None
blade_starting_positions	See Qoolqit's documentation (external) TYPE: Tensor | None
blade_dimensions	See Qoolqit's documentation (external) TYPE: list[int]
draw_steps	Show generated graph at each step of the optimization. Defaults to False. TYPE: bool
animation_save_path	If provided, path to save animation. Defaults to None. TYPE: str | None
min_distance	Minimum atom separation (μm). If not None, the resulting register will be normalized so that the minimum atom separation is equal to this value. Should be 1.001 when using the Heuristic Drive-Shaping, and None when using the Optimized Drive-Shaping. Defaults to 1.001. TYPE: float | None

LocalEmulator(backend_type=AutoLocalEmulatorBackend, **kwargs)

Bases: LocalEmulator

Local quantum emulator with automatic backend selection.

This class wraps qoolqit.LocalEmulator and automatically selects the optimal local backend based on the quantum register size. It provides the same interface as the base LocalEmulator but with improved performance through intelligent backend selection.

The optimal backend selection follows these guidelines: - Small problems (< 15 qubits): QutipBackendV2 - Medium problems (15-25 qubits): SVBackend - Large problems (≥ 26 qubits): MPSBackend

PARAMETER	DESCRIPTION
backend_type	Backend type to use. Defaults to AutoLocalEmulatorBackend for automatic selection. TYPE: type DEFAULT: AutoLocalEmulatorBackend
**kwargs	Additional keyword arguments passed to the base LocalEmulator. TYPE: Any DEFAULT: {}

Example

Source code in qubosolver/backends.py

def __init__(
    self, backend_type: Type[EmulatorBackend] = AutoLocalEmulatorBackend, **kwargs: Any
) -> None:
    super().__init__(backend_type=backend_type, **kwargs)

run(program, *args, **kwargs)

Run the quantum program with backend tractability warning.

PARAMETER	DESCRIPTION
program	The quantum program to execute TYPE: QuantumProgram
*args	Additional positional arguments TYPE: Any DEFAULT: ()
**kwargs	Additional keyword arguments TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Any	The execution results from the local backend

Source code in qubosolver/backends.py

def run(self, program: qoolqit.QuantumProgram, *args: Any, **kwargs: Any) -> Any:
    """Run the quantum program with backend tractability warning.

    Args:
        program: The quantum program to execute
        *args: Additional positional arguments
        **kwargs: Additional keyword arguments

    Returns:
        The execution results from the local backend
    """
    _warn_suboptimal_backend(self._backend_type, program.register.n_qubits)
    return super().run(program, *args, **kwargs)

RemoteEmulator(backend_type=EmuFreeBackendV2, **kwargs)

Bases: RemoteEmulator

Remote quantum emulator with automatic backend selection.

This class wraps qoolqit.RemoteEmulator and provides backend selection recommendations based on quantum register size and tractability constraints.

Backend selection guidelines based on computational tractability: - Small problems (< 15 qubits): EmuFreeBackendV2 (default) - Medium problems (15-25 qubits): EmuSVBackend - Large problems (≥ 26 qubits): EmuMPSBackend

Note: EmuFreeBackendV2 becomes intractable beyond ~15 qubits, similar to its local counterpart QutipBackendV2. For larger problems, EmuSVBackend and EmuMPSBackend are necessary. Fees may apply for remote execution.

PARAMETER	DESCRIPTION
backend_type	Backend type to use. Defaults to EmuFreeBackendV2. TYPE: type DEFAULT: EmuFreeBackendV2
**kwargs	Additional keyword arguments passed to the base RemoteEmulator. TYPE: Any DEFAULT: {}

Example

Source code in qubosolver/backends.py

def __init__(
    self, backend_type: Type[RemoteEmulatorBackend] = EmuFreeBackendV2, **kwargs: Any
) -> None:
    super().__init__(backend_type=backend_type, **kwargs)

run(program, *args, **kwargs)

Run the quantum program with backend tractability warning.

PARAMETER	DESCRIPTION
program	The quantum program to execute TYPE: QuantumProgram
*args	Additional positional arguments TYPE: Any DEFAULT: ()
**kwargs	Additional keyword arguments TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Any	The execution results from the remote backend

Source code in qubosolver/backends.py

def run(self, program: qoolqit.QuantumProgram, *args: Any, **kwargs: Any) -> Any:
    """Run the quantum program with backend tractability warning.

    Args:
        program: The quantum program to execute
        *args: Additional positional arguments
        **kwargs: Additional keyword arguments

    Returns:
        The execution results from the remote backend
    """
    _warn_suboptimal_backend(self._backend_type, program.register.n_qubits)
    return super().run(program, *args, **kwargs)

SolverConfig

Bases: Config

A SolverConfig instance defines how a QUBO problem should be solved. We specify whether to use a quantum or classical approach, which backend to run on, and additional execution parameters.

ATTRIBUTE	DESCRIPTION
config_name	The name of the current configuration. Defaults to ''. TYPE: str
use_quantum	Whether to solve using a quantum approach (True) or a classical approach (False). Defaults to True. TYPE: bool
embedding	Embedding part configuration of the solver. TYPE: EmbeddingConfig
drive_shaping	Drive-shaping part configuration of the solver. TYPE: DriveShapingConfig
classical	Classical part configuration of the solver. TYPE: ClassicalConfig
backend	backend for running quantum programs. Note that parameters such as dt are directly set when creating LocalEmulator | RemoteEmulator | QPU, hence they are deprecated compared to previous qubo-solver versions. Also the number of shots is set there as well. Defaults to a LocalEmulator using qutip. TYPE: LocalEmulator | RemoteEmulator | QPU
device	The quantum device specification. Defaults to AnalogDeviceWithDMM. TYPE: Device
do_postprocessing	Whether we apply post-processing (True) or not (False). Defaults to True. TYPE: bool
do_preprocessing	Whether we apply pre-processing (True) or not (False). Defaults to True. TYPE: bool
activate_trivial_solutions	Whether calculate trivial solutions (True) or not (False). Defaults to True. TYPE: bool
decompose	which decomposition configuration to use when solving large QUBOs. Defaults to None, i.e. no decomposition is applied. TYPE: DecompositionConfig | None

from_kwargs(**kwargs) classmethod

Create an instance based on entries of other configs.

Note that if any of the keywords ("embedding", "drive_shaping", "classical") are present in kwargs, the values are taken directly.

RETURNS	DESCRIPTION
SolverConfig	An instance from values. TYPE: SolverConfig

Source code in qubosolver/config.py

@classmethod
def from_kwargs(cls, **kwargs: dict) -> SolverConfig:
    """Create an instance based on entries of other configs.

    Note that if any of the keywords
    ("embedding", "drive_shaping", "classical")
    are present in kwargs, the values are taken directly.

    Returns:
        SolverConfig: An instance from values.
    """
    # Extract fields from pydantic BaseModel
    embedding_fields = {k: v for k, v in kwargs.items() if k in EmbeddingConfig.model_fields}
    drive_shaping_fields = {
        k: v for k, v in kwargs.items() if k in DriveShapingConfig.model_fields
    }
    classical_fields = {k: v for k, v in kwargs.items() if k in ClassicalConfig.model_fields}
    decompose_fields = {
        k: v for k, v in kwargs.items() if k in DecompositionConfig.model_fields
    } or kwargs.get("decompose", {})

    solver_fields: dict[str, Any] = {
        k: v
        for k, v in kwargs.items()
        if k in cls.model_fields
        and k not in ("embedding", "drive_shaping", "classical", "decompose")
    }
    solver_fields["embedding"] = EmbeddingConfig.model_validate(
        kwargs.get("embedding", embedding_fields)
    )
    solver_fields["drive_shaping"] = DriveShapingConfig.model_validate(
        kwargs.get("drive_shaping", drive_shaping_fields)
    )
    solver_fields["classical"] = ClassicalConfig.model_validate(
        kwargs.get("classical", classical_fields)
    )
    if decompose_fields:
        solver_fields["decompose"] = DecompositionConfig.model_validate(decompose_fields)

    return cls.model_validate(solver_fields)

print_specs()

Print specs.

Source code in qubosolver/config.py

def print_specs(self) -> None:
    """Print specs."""
    print(self.specs())

specs()

Return the specs of the SolverConfig, that is all attributes.

RETURNS	DESCRIPTION
dict	Dictionary of specs key-values. TYPE: str

Source code in qubosolver/config.py

def specs(self) -> str:
    """Return the specs of the `SolverConfig`, that is all attributes.

    Returns:
        dict: Dictionary of specs key-values.
    """
    return "\n".join(
        f"{k}: ''" if v == "" else f"{k}: {v}" for k, v in self.model_dump().items()
    )

compiler_profile(config)

Determines the appropriate compiler profile based on the drive shaping method.

PARAMETER	DESCRIPTION
config	The solver configuration to inspect. TYPE: SolverConfig

RETURNS	DESCRIPTION
CompilerProfile	CompilerProfile.WORKING_POINT for the optimized drive shaper, CompilerProfile.MAX_ENERGY otherwise. TYPE: CompilerProfile

Source code in qubosolver/config.py

def compiler_profile(config: SolverConfig) -> CompilerProfile:
    """Determines the appropriate compiler profile based on the drive shaping method.

    Args:
        config (SolverConfig): The solver configuration to inspect.

    Returns:
        CompilerProfile: `CompilerProfile.WORKING_POINT` for the optimized drive
            shaper, `CompilerProfile.MAX_ENERGY` otherwise.
    """
    if config.drive_shaping.drive_shaping_method == DriveType.OPTIMIZED:
        return CompilerProfile.WORKING_POINT
    return CompilerProfile.MAX_ENERGY

max_duration_ratio(config)

Computes the maximum pulse duration ratio for the configured device.

Returns 0.99 to give a small safety margin below the device's maximum duration, or None if the device has no duration limit.

PARAMETER	DESCRIPTION
config	The solver configuration to inspect. TYPE: SolverConfig

RETURNS	DESCRIPTION
float | None	float | None: 0.99 if the device has a maximum duration, else None.

Source code in qubosolver/config.py

def max_duration_ratio(config: SolverConfig) -> float | None:
    """Computes the maximum pulse duration ratio for the configured device.

    Returns 0.99 to give a small safety margin below the device's maximum
    duration, or None if the device has no duration limit.

    Args:
        config (SolverConfig): The solver configuration to inspect.

    Returns:
        float | None: 0.99 if the device has a maximum duration, else None.
    """
    if config.device.specs["max_duration"] is None:
        return None
    return 0.99