Calculate the Ground State Energy Using the BEAST-VQE

Goal

Run a BEAST-VQE calculation for a prepared ground-state problem and obtain the ground-state energy.

Prerequisites

A ground-state problem (see Construct a Ground State Energy Problem)

Steps

Quick start: Build the default BEAST-VQE calculator

The calculator_creator() is a fluent builder (see Understanding and Using Kvantify Qrunch’s Fluent Builder Pattern) that configures and returns a GroundStateProblemCalculator. By default, .vqe().beast() builds a BEAST-VQE calculator with conservative defaults to avoid lengthy runs on real hardware.
```
import qrunch as qc

beast_vqe_calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .beast()
    .create()
)
```
Use the default BEAST-VQE calculator to calculate the ground state energy

You can now calculate the result from an existing ground_state_problem:
```
result = beast_vqe_calculator.calculate(ground_state_problem)
```
The result is a GroundStateProblemCalculatorResult object, which contains:
- Electronic energy of the active electrons
- Electronic energy of all electrons
- Total molecular energy
- Electronic energy per macro iteration (list of values for each VQE iteration)

Customize the VQE settings

The most common setting to adjust is max_iterations in IterativeVqeOptions. The default is intentionally low to avoid long, costly runs on hardware — but often insufficient for convergence.

import qrunch as qc

adaptive_vqe_options = qc.options.IterativeVqeOptions(
    max_iterations=100,
)

beast_vqe_calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .beast()
    .with_options(options=adaptive_vqe_options)
    .create()
)

See the API reference for IterativeVqeOptions for the full list of options.

you can configure additional options before calling .create():

Set the estimator:
```
.with_estimator(my_estimator)
```

Setting an estimator to be used for parameter optimization.

Define number of measurement shots:
```
.with_estimator_shots(1000)
```

Setting the number of shots to use in the estimator when doing parameter optimization. Setting to None uses an exact simulator.

Choose classical minimizer:

.choose_minimizer()
  # .<pick-a-minimizer>(...)

You can choose which classical minimizer you want to use to optimize the parameters. See Choose a Minimizer for available options.

Choose reminimizer:

.choose_reminimizer()
  # .<pick-a-minimizer>(...)

You can choose a classical minimizer if you want to re-optimize the parameters at the end of a VQE run. See Choose a Minimizer for available options.

Set stopping criteria:

.choose_stopping_criterion()
# .<pick-a-stopping-criterion>(...)

You can choose the stopping criterion for the iterative VQE. See Choose a Stopping Criterion for available options.

Select a custom gate selector:
```
.with_gate_selector(my_gate_selector)
```

You can provide a custom gate selector to control which excitation gate is added at each iteration. See Create a FAST Gate Selector for how to build a gate_selector.

Configure data persistence:

.choose_data_persister_manager()
# .<pick-a-persister>(...)

You can choose how and where to save/load intermediate data during the VQE run. See Choose a Data Persister Manager for available options.

Configure Analytical BEAST-VQE:

.with_analytical_beast_basic_vqe(active=True)

Choose to use the analytical basic vqe inside each adaptive iteration.

Instead of having the minimizer call the estimator directly, the estimator is first called to generate an analytical expression for the energy as a function of the gate parameter. This expression is then passed to the minimizer, requiring no more measurements.

This results in the estimator being called only 4 times per adaptive iteration, instead of a minimum of 10 times for a normal basic-VQE with the FftMinimizer.

Note: This feature only works for BEAST-VQE with last parameter optimization - the default. So if you have chosen a different minimizer, you may need to deactivate this feature.

OO-BEAST-VQE (Orbital-Optimized BEAST-VQE)

OO-BEAST-VQE augments BEAST-VQE with orbital optimization at each iteration, improving accuracy for some systems.

import qrunch as qc

adaptive_vqe_options = qc.options.IterativeVqeOptions(
    max_iterations=100,
)

oo_beast_vqe_calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative_with_orbital_optimization()
    .beast()
    .with_options(options=adaptive_vqe_options)
    .create()
)

The OO-BEAST-VQE has all the same configuration options as BEAST-VQE, and in addition you can also:

Define an orbital optimizer:

.with_orbital_optimizer(orbital_optimizer)

See Create an Orbital Optimizer for how to construct the orbital_optimizer.

Set stopping criterion for the orbital optimizer:

.choose_orbital_optimizer_stopping_criterion()
# .<pick-a-stopping-criterion>(...)

See Choose a Stopping Criterion for available options.

Optimal performance

To optimize performance and cost when running on real quantum hardware, consider the following:

import qrunch as qc

adaptive_vqe_options = qc.options.IterativeVqeOptions(
    max_iterations=100,
)

beast_vqe_calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .beast()
    .with_options(options=adaptive_vqe_options)
    .with_analytical_beast_basic_vqe(active=True)
    .choose_minimizer()
    .last_variable_fft()
    .create()
)

This configuration uses the FFT minimizer for the optimization of the parameter of each gate, and it uses a specialized analytical BEAST-VQE that reduces the number of quantum measurements needed. As with all greedy algorithms, there is a trade-off between performance and accuracy, so validate the results carefully.

It is possible to improve the accuracy by using an efficient reminimizer.

Verify the Result

Check that the result.total_energy is correct.
For simulator runs, repeated calculations should produce the same .value with .error close to zero unless the simulator has a finite shot count.
On hardware, .error will reflect shot noise from finite measurements, and other noise sources, such as decoherence.
An error like Exception: Invalid single excitation gate. You might want to use mixed spin? indicate that you have mixed a calculator that assume Bosonic encoding with a VQE instance that uses Fermionic encoding.