VQEHyperparameterSweep

class VQEHyperparameterSweep(ansatze, molecule_transformer=None, hamiltonians=None, optimizer=None, max_iterations=10, **kwargs)

Bases: ProgramEnsemble

Allows user to carry out a grid search across different values for the ansatz and the bond length used in a VQE program.

Initialize a VQE hyperparameter sweep.

Parameters:

• ansatze (Sequence[Ansatz]) – A sequence of ansatz circuits to test.

• hamiltonians (Sequence[Operator] | None) – A sequence of Hamiltonians to use for the VQE runs. If None (the default), no Hamiltonians are provided explicitly and molecule-based VQE runs will use their default Hamiltonians.

• molecule_transformer (MoleculeTransformer | None) – A MoleculeTransformer object defining the configuration for generating the molecule variants. If None (the default), the provided hamiltonians are used directly and no molecular transformation is performed.

• optimizer (Optimizer | None) – The optimization algorithm for the VQE runs.

• max_iterations (int) – The maximum number of optimizer iterations for each VQE run.

• **kwargs – Forwarded to the parent class.

Methods Summary

aggregate_results()	Find the best ansatz and bond configuration from all VQE runs.
create_programs()	Create VQE programs for all combinations of ansätze and molecule variants.
visualize_results([graph_type])	Visualize the results of the VQE problem.

Methods Documentation

aggregate_results()

Find the best ansatz and bond configuration from all VQE runs.

Compares the final energies across all ansatz/molecule combinations and returns the configuration that achieved the lowest ground state energy.

Returns:

A tuple containing:

• best_config (tuple): (ansatz_name, bond_modifier) of the best result.

• best_energy (float): The lowest energy achieved.

Return type:

tuple

Raises:

RuntimeError – If programs haven’t been run or have empty losses.

create_programs()

Create VQE programs for all combinations of ansätze and molecule variants.

Generates molecule variants using the configured MoleculeTransformer, then creates a VQE program for each (ansatz, molecule_variant) pair.

Note

Program IDs are tuples of (ansatz_name, bond_modifier_value).

visualize_results(graph_type='line')

Visualize the results of the VQE problem.