VariationalQuantumAlgorithm

class VariationalQuantumAlgorithm(backend, optimizer=None, seed=None, progress_queue=None, early_stopping=None, **kwargs)

Bases: ObservableMeasuringMixin, QuantumProgram

Base class for variational quantum algorithms.

This class provides the foundation for implementing variational quantum algorithms in Divi. It handles circuit execution, parameter optimization, and result management for algorithms that optimize parameterized quantum circuits to minimize cost functions.

Variational algorithms work by: 1. Generating parameterized quantum circuits 2. Executing circuits on quantum hardware/simulators 3. Computing expectation values of cost Hamiltonians 4. Using classical optimizers to update parameters 5. Iterating until convergence

Variables:

• _losses_history – History of loss values during optimization.

• _param_history (list[ndarray[tuple[Any, ...], dtype[double]]]) – Raw per-callback parameter batches; use param_history() to read copies with optional filtering.

• _final_params – Final optimized parameters.

• _best_params – Parameters that achieved the best loss.

• _best_loss (float) – Best loss achieved during optimization.

• _circuits – Generated quantum circuits.

• _total_circuit_count (int) – Total number of circuits executed.

• _total_run_time (float) – Total execution time in seconds.

• _seed – Random seed for parameter initialization.

• _rng – Random number generator.

• _grouping_strategy – Strategy for grouping quantum operations.

• _qem_protocol – Quantum error mitigation protocol.

• _cancellation_event – Event for graceful termination.

• _cost_circuit – Lazily-built cost MetaCircuit for this program (or None).

Initialize the VariationalQuantumAlgorithm.

This constructor is specifically designed for hybrid quantum-classical variational algorithms. The instance variables n_layers and n_params_per_layer must be set by subclasses, where: - n_layers is the number of layers in the quantum circuit. - n_params_per_layer is the number of parameters per layer.

For exotic variational algorithms where these variables may not be applicable, the _initialize_param_sets method should be overridden to generate the starting parameters for a fresh optimization run.

Parameters:

• backend (CircuitRunner) – Quantum circuit execution backend.

• optimizer (Optimizer | None) – The optimizer to use for parameter optimization. Required — passing None (or omitting it) raises ValueError.

• seed (int | None) – Random seed for parameter initialization. Defaults to None.

• progress_queue (Queue | None) – Queue for progress reporting. Defaults to None.

• early_stopping (EarlyStopping | None) – Early stopping controller. When provided, the optimization loop will be halted if any of the configured criteria are met (e.g. patience exceeded, gradient below threshold, cost variance settled). Defaults to None.

Keyword Arguments:

• grouping_strategy (str) – Strategy for partitioning Hamiltonian terms into compatible measurement groups; one circuit is executed per group. Options: "qwc" (qubit-wise-commuting — most compact), "wires" (group by support wires), or None (one circuit per term). Defaults to "qwc".

• shot_distribution (str or callable(), optional) –

  Focus the backend’s shot budget on the Hamiltonian terms that matter most. Without this option, every measurement group is sampled with the backend’s full shot count, even tiny terms with little impact on the final energy. With shot_distribution set, the same total budget is split across groups according to their importance — reducing variance without spending more shots.

  Available strategies:

  • "uniform" — equal split across groups.

  • "weighted" — proportional to per-group coefficient L1 norm; dominant Hamiltonian terms get more shots.

  • "weighted_random" — multinomial sample of the same probabilities; may drop more low-weight groups than the deterministic "weighted" for the same budget.

  • A callable (group_l1_norms, total_shots) -> per_group_shots for fully custom allocation.

  Example:

  vqe = MyVQA(
      backend=QiskitSimulator(shots=1000),
      shot_distribution="weighted",
  )
  vqe.run()
  

  Only valid when sampling is actually used. Setting it on a backend that computes expectation values analytically (grouping_strategy="_backend_expval") is rejected because shots are ignored in that mode. Defaults to None (every group receives the full shot budget).

• precision (int) – Forwarded to QuantumProgram — decimal places for numeric parameter values in QASM conversion. Higher values produce longer QASM strings (more data sent to cloud backends); lower values trade resolution for compactness. Defaults to DEFAULT_PRECISION.

Note

Solution-extracting subclasses (VQE/QAOA/PCE) also accept decode_solution_fn via SolutionSamplingMixin.

Attributes Summary

best_loss	Get the best loss achieved so far.
best_params	Get a copy of the parameters that achieved the best (lowest) loss.
cost_circuit	The cost MetaCircuit for this program (lazily built, cached).
final_params	Get a copy of the final optimized parameters.
losses_history	Get a copy of the optimization loss history.
min_losses_per_iteration	Get the minimum loss value for each iteration.
n_params_per_layer	Number of trainable parameters per ansatz layer.
stop_reason	Reason the optimization was stopped early, or None.
viz	Access visualization helpers for this variational program.

Methods Summary

cost_preprocessor()	The preprocessor driving optimization: expectation of the cost observable.
get_expected_param_shape()	Get the expected shape for initial parameters.
has_results()	Return True once the program has produced results.
load_state(checkpoint_dir, backend[, ...])	Load program state from a checkpoint directory.
param_history([mode])	Parameter vectors recorded at each optimization callback.
run([initial_params, ...])	Run the variational quantum algorithm.
save_state(checkpoint_config)	Save the program state to a checkpoint directory.

Attributes Documentation

best_loss

Get the best loss achieved so far.

Returns:

The best loss achieved so far.

Return type:

float

best_params

Get a copy of the parameters that achieved the best (lowest) loss.

Returns:

Copy of the best parameters. Modifications to this array

will not affect the internal state.

Return type:

npt.NDArray[np.float64]

cost_circuit

The cost MetaCircuit for this program (lazily built, cached).

Note: When used with ProgramEnsemble, this is initialized sequentially in the main thread before parallel execution to avoid thread-safety issues.

final_params

Get a copy of the final optimized parameters.

Returns:

Copy of the final parameters. Modifications to this array

will not affect the internal state.

Return type:

npt.NDArray[np.float64]

losses_history

Get a copy of the optimization loss history.

Each entry is a dictionary mapping parameter indices to loss values.

Returns:

Copy of the loss history. Modifications to this list

will not affect the internal state.

Return type:

list[dict]

min_losses_per_iteration

Get the minimum loss value for each iteration.

Returns a list where each element is the minimum (best) loss value across all parameter sets for that iteration.

Returns:

List of minimum loss values, one per iteration.

Return type:

list[float]

n_params_per_layer

Number of trainable parameters per ansatz layer.

Used by the base class to compute the total parameter count as n_layers * n_params_per_layer.

stop_reason

Reason the optimization was stopped early, or None.

Returns:

The StopReason

that triggered early stopping, or None if optimization completed normally or has not been run yet.

Return type:

StopReason | None

viz

Access visualization helpers for this variational program.

The returned object exposes a thin convenience wrapper over the standalone divi.viz API, so scans can be written either as divi.viz.scan_1d(program, ...) or program.viz.scan_1d(...).

Returns:

Convenience wrapper bound to this program instance.

Return type:

ProgramViz

Methods Documentation

cost_preprocessor()

The preprocessor driving optimization: expectation of the cost observable.

Pass it to evaluate() to measure the cost at chosen parameters, e.g. program.evaluate(params, program.cost_preprocessor()).

Return type:

CircuitPreprocessor

get_expected_param_shape()

Get the expected shape for initial parameters.

Returns:

Shape (n_param_sets, n_layers * n_params_per_layer) that

initial parameters should have for this quantum program.

Return type:

tuple[int, int]

has_results()

Return True once the program has produced results.

Return type:

bool

classmethod load_state(checkpoint_dir, backend, subdirectory=None, **kwargs)

Load program state from a checkpoint directory.

Return type:

VariationalQuantumAlgorithm

param_history(mode='all_evaluated')

Parameter vectors recorded at each optimization callback.

Parameters:

mode (Literal['all_evaluated', 'best_per_iteration']) –

Which rows to return for each iteration:

• "all_evaluated" — full batch from the callback, shape (n_param_sets, n_params) per iteration (mirrors losses_history population layout).

• "best_per_iteration" — single best member by loss for that iteration, shape (1, n_params) per iteration.

Returns:

One array per completed callback. Use numpy.vstack(...) for a 2D sample matrix (e.g. PCA).

Return type:

list[ndarray[tuple[Any, ...], dtype[double]]]

Raises:

RuntimeError – If internal loss and parameter histories are out of sync.

run(initial_params=None, perform_final_computation=True, checkpoint_config=None, **kwargs)

Run the variational quantum algorithm.

The outputs are stored in the algorithm object and can be accessed via properties such as total_circuit_count, total_run_time, losses_history, and best_params.

Parameters:

• initial_params (ndarray[tuple[Any, ...], dtype[double]] | None) – Optional initial parameter sets for a fresh optimization run. Must have shape (n_param_sets, n_layers * n_params_per_layer). Cannot be combined with a checkpoint-resumed optimizer state.

• perform_final_computation (bool) – Whether to perform final computation after optimization completes. Typically, this step involves sampling with the best found parameters to extract solution probability distributions. Set this to False in warm-starting or pre-training routines where the final sampling step is not needed. Defaults to True.

• checkpoint_config (CheckpointConfig | None) – Checkpoint configuration. If None, no checkpointing is performed.

• **kwargs – Additional keyword arguments for subclasses.

Returns:

Returns self for method chaining.

Return type:

VariationalQuantumAlgorithm

save_state(checkpoint_config)

Save the program state to a checkpoint directory.

Return type:

Path