Construct a Ground State Energy Problem

A ground state energy problem bundles all computational ingredients needed to evaluate the quantum-mechanical ground state energy of a molecule’s electronic Hamiltonian. It includes:

• one- and two-electron integrals

• electron configuration (number of spatial/spin orbitals, number of spin up and spin down electrons)

• required energy contributions (e.g., nuclear repulsion) to form the total molecular ground state energy.

Goal

Build a ground state energy problem.

The ground state energy problem 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

• A molecular configuration (see Create a MolecularConfiguration)

Steps

1. Build the ground state problem builder

   The problem_builder_creator builder guides you to a consistent setup. .ground_state().standard() selects a full ground state electronic structure problem builder. See Understanding and Using Kvantify Qrunch’s Fluent Builder Pattern for details on the builder pattern and how to use them.

   

   You can create a ground state problem builder like this:

   import qrunch as qc
   
   problem_builder = (
       qc.problem_builder_creator()
       .ground_state()
       .standard()
       .create()
   )
   

   The main choices you can make when building a ground state problem builder are:

   • .standard(): builds a standard ground state problem.

   • .projective_embedding(): builds a Wavefunction-in-DFT projection based embedding ground state problem builder. See Create a Projective-Embedding Ground-State Problem for details.

2. Build the ground state problem

   Once a problem builder has been created, you need a molecular configuration to build the problem. See Create a MolecularConfiguration for details on how to create a molecular configuration.

   You can call either .build_restricted(molecular_configuration) to create the restricted problem:

   restricted_problem = problem_builder.build_restricted(molecular_configuration)
   

   or .build_unrestricted(molecular_configuration) to create the unrestricted problem:

   unrestricted_problem = problem_builder.build_unrestricted(molecular_configuration)
   

   The terms restricted and unrestricted describe how the spin degrees of freedom are treated. A restricted calculation assumes paired electrons share the same spatial orbital, differing only by spin. This means the molecular orbitals and molecular integrals are identical for spin-up and spin-down electrons.

Add Problem Modifiers (e.g., Active Space)

You can add modifiers such as a restriction of the active space. See Understanding and Using Kvantify Qrunch’s Fluent Builder Pattern for details on the .add_… methods.

import qrunch as qc

problem_builder = (
    qc.problem_builder_creator()
    .ground_state()
    .standard()
    .add_problem_modifier()
    # .<pick-one-modifier>(...)
    .create()
)

The options are:

• .active_space(..): Adds an active space modifier. See Define an Active Space (Complete Active Space) for details.

• .to_dense_integrals(): Adds a transformation to a dense format. See Choose Electron-Repulsion Integral Builder for more details.

Choose Electron Repulsion Integral Builder

You can pick the different electron repulsion integral options.

import qrunch as qc

problem_builder = (
    qc.problem_builder_creator()
    .ground_state()
    .standard()
    .choose_repulsion_integral_builder()
    # .<pick-one-integral-builder>(...)
    .create()
)

See Choose Electron-Repulsion Integral Builder for more details.

See Also

• Create a MolecularConfiguration

• API reference: ground_state_problem

Next Step

You can use the ground-state problem to calculate the ground-state energy:

• Calculate the Ground State Energy Using the FAST-VQE