Build a VQE Calculator

Goal

Use the fluent qc.calculator_creator() API to select and create a VQE calculator:

  • Fixed-ansatz VQE (static circuit)

  • Iterative VQE (adaptive circuit), e.g. FAST-VQE, ADAPT-VQE or BEAST-VQE

  • Iterative + Orbital Optimization (OO-FAST-VQE, OO-ADAPT-VQE, OO-BEAST-VQE)

  • Hybrid method that accelerates a standard (fermionic encoding) run with a BEAST (bosonic encoding of electron pairs) run

The calculator is a key component of a typical workflow for a quantum chemistry calculation which follows three main steps:

  1. Define the molecular configuration: Specify the atoms, their coordinates, and the basis set. This creates a molecular configuration that encodes the physical system you want to study.

  2. Build the problem: Use the molecular configuration to construct a problem object (such as a ground state energy problem). This bundles all necessary quantum-chemical data (integrals, electron counts, etc.) for the calculation.

  3. Choose and run the calculator: Select a calculator (e.g., FAST-VQE, BEAST-VQE, ADAPT-VQE) that knows how to solve the problem. The calculator takes the problem object and computes the desired properties, such as the total energy.

This “molecule → problem → calculator” flow ensures a clear separation between system definition, problem formulation, and computational method, making it easy to swap components.

Prerequisites

Overview: Narrowing by Intent

Start from the calculator creator:

import qrunch as qc

calc = qc.calculator_creator()

Then narrow down:

  • Choose VQE family:

    • .vqe().fixed_ansatz() → Fixed circuit

    • .vqe().iterative() → Iterative circuit (grows by adding gates at each iteration)

    • .vqe().iterative_with_orbital_optimization() → Iterative + OO (orbital optimization each iteration)

  • Within an iterative family, pick:

    • .standard() → FAST-VQE / ADAPT-VQE (fermionic encoding)

    • .beast() → BEAST-VQE (paired-electron, bosonic encoding of electron pairs)

Finally, build with .create(). For details on how to pass more detailed components (gate selectors, minimizers, options, etc.) please check their respective guides; here we focus on the high-level flow.

Quick Starts

import qrunch as qc

calculator = (
    qc.calculator_creator()
    .vqe()
    .fixed_ansatz()
    .create()
)

Use when you have a predefined circuit/ansatz and only want to optimize parameters.

import qrunch as qc

fast_calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .standard()
    .create()
)

See Calculate the Ground State Energy Using the FAST-VQE for more detail.

import qrunch as qc

beast_calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .beast()
    .create()
)

See Calculate the Ground State Energy Using the BEAST-VQE.

Run BEAST to get a good starting point and then continue with standard (fermionic) iterative VQE.

import qrunch as qc

fast_calculator = (
    qc.calculator_creator().vqe().iterative().standard().create()
)
beast_calculator = (
    qc.calculator_creator().vqe().iterative().beast().create()
)

hybrid_calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .paired_electron_approximation_accelerated_standard()
    .with_beast_calculator(beast_calculator)
    .with_standard_calculator(fast_calculator)
    .create()
)

import qrunch as qc

oo_fast_calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative_with_orbital_optimization()
    .standard()
    .create()
)

import qrunch as qc

oo_beast_calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative_with_orbital_optimization()
    .beast()
    .create()
)

Note

Creating an ADAPT-VQE calculator instead of the default FAST-VQE calculator is a matter of selecting the right gate selector. See Create an ADAPT Gate Selector and Create a FAST Gate Selector.

Calling the Calculator

All calculators expose a common interface:

result = calculator.calculate(ground_state_problem)