Skip to main contentIBM Quantum Documentation

HI-VQE Chemistry - A Qiskit Function by Qunova Computing

Note

This documentation is relevant to IBM Quantum® Platform Classic. If you need the newer version, go to the new IBM Quantum Platform documentation.

Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan users. They are in preview release status and subject to change.


Overview

In quantum chemistry, the electronic structure problem focuses on finding the solutions to the electronic Schrödinger equation - the quantum wave functions describing the behavior of the system's electrons. These wave functions are vectors of complex amplitudes, with each amplitude corresponding to the contribution of a possible electron configuration.

The ground state is the lowest energy wave function of the system and has a special importance in the study of molecular systems. The most accurate approach for computing the ground state considers all possible electron configurations, but this becomes intractable for larger systems since the number of configurations grows exponentially with system size.

The Handover Iterative Variational Quantum Eigensolver (HI-VQE) is an innovative hybrid quantum-classical method for accurately estimating the ground state of molecular systems. It integrates quantum hardware with classical computing, using quantum processors to efficiently explore candidate electron configurations and calculating the resulting wave function on classical computers. By generating compact yet chemically accurate wave functions, HI-VQE enhances research and discovery in quantum chemistry and materials science.

Image showing an overview of Qunova's HI-VQE algorithm

HI-VQE reduces the computational complexity of the electronic structure problem by efficiently estimating the ground state with high accuracy. It focuses on a carefully selected subset of the most relevant electron configurations, optimizing both accuracy and efficiency.

Combining the strengths of both classical and quantum computers, HI-VQE iteratively refines and improves the current estimate wave function. Its unique subspace construction techniques help make configuration selection more efficient, so that users have greater computational control and improved accuracy in quantum chemistry simulations.

If you would like to learn about the algorithm in more depth, you can read the associated research paper.


Description

The number of electron configurations for a molecular system grows exponentially with system size. However, for certain electronic states, such as the ground state, it is common that only a small fraction of configurations significantly contribute to the state’s energy. Selected configuration interaction (SCI) methods exploit this sparsity to reduce computational costs by identifying and focusing on the most relevant configurations. This subset of configurations is referred to as a subspace.

HI-VQE leverages the inherent efficiency of quantum computers for representing molecular systems to aid the subspace search. It integrates classical and quantum subroutines to solve the electronic structure problem with high accuracy. Unlike existing quantum SCI methods, HI-VQE combines variational training, iterative subspace construction, and pre-diagonalization configuration screening to enhance efficiency by reducing quantum measurements, iterations, and classical diagonalization costs. HI-VQE can therefore be applied to larger molecular systems which require more qubits, and reduces the cost to solve a problem of a given size to the same degree of accuracy.

Image showing a detailed description of each step in Qunova's HI-VQE algorithm.

To compute a system's ground state, HI-VQE first uses the classical chemistry package PySCF to generate a molecular representation from user-provided inputs, such as the molecular geometry and other molecular information. It then enters a hybrid quantum-classical optimization loop, iteratively refining a subspace to optimally represent the ground state while minimizing the number of configurations included. The loop continues until convergence criteria, such as subspace size or energy stability, are met, after which the computed ground state wave function and energy are output. These results can be used to construct accurate potential energy surfaces and perform further analysis of the system.

The optimization loop focuses on adjusting a quantum circuit’s parameters to generate a high-quality subspace. HI-VQE offers three quantum circuit options: ExcitationPreserving, EfficientSU2, and LUCJ. The optimization is initialized close to the Hartree-Fock reference state due to its general suitability. The circuit is then executed on a quantum device and configurations are sampled from the resulting quantum state before being returned as binary strings. Due to quantum device noise, some sampled configurations may be physically invalid, failing to conserve electron number or spin. HI-VQE addresses this using the configuration recovery process from the qiskit-addon-sqd package, so that users can either correct invalid configurations or discard them.

The valid configurations then undergo an optional screening step to remove those predicted to contribute minimally. This reduces the dimension of the subspace, thereby lowering the cost of the diagonalization step. If the screening is enabled, then a preliminary subspace Hamiltonian is constructed from the valid configurations and a diagonalization is performed with very loose termination critieria. Though the accuracy of the resulting amplitudes for each configuration is low, it is effective for predicting which configurations to leave out of the subspace this iteration, and it is fast to compute.

The selected configurations are added to the subspace, and the system's Hamiltonian is projected into this subspace. The subspace updates iteratively, preserving the most relevant configurations across iterations. This approach contrasts with alternative methods because the quantum circuit does not need to approximate the full ground state at each step.

Next, the subspace Hamiltonian is classically diagonalized to obtain the lowest eigenvalue and its corresponding eigenvector, representing an approximation of the ground state and its energy. As the subspace quality improves through iterations, the computed ground state better approximates the true ground state. An additional screening step can be performed at this point to remove any configurations from the subspace that don't have a substantial contribution to the computed ground state. This step ensures that the subspace carried into the next iteration is as compact as possible. This is evaluated based on the amplitudes that are returned by the diagonalization, as these represent each configuration's importance contribution to the computed ground state.

A convergence check then determines whether further training would improve results. If so, then an optional classical expansion step is performed, the quantum circuit parameters are updated to further minimize the computed energy, and the process repeats. The classical expansion step generates additional configurations for the subspace, supplementing the configurations sampled from the quantum device. It first identifies the configuration with the largest amplitude in the diagonalization results, before generating new configurations with single and double excitations from the identified configuration. The desired number of these configurations are then added to the subspace.

Once it is determined that the iterations have converged, HI-VQE returns the computed ground state (in the form of the states in the subspace and their amplitudes in the ground state wave function), its energy, and an energy variance measure that gives an indication of whether the computed state forms an eigenstate of the system's Hamiltonian.

Users are able to decide the quantum circuit used and the number of shots taken for each quantum circuit, as well as control the subspace size or enable the classical generation of additional configurations to assist the quantum generated configurations. In this way users can tailor the behavior of HI-VQE to suit their desired applications.


Get started

First, request access to the function.

Then, authenticate using your IBM Quantum® API key and select the Qiskit Function as follows:

from qiskit_ibm_catalog import QiskitFunctionsCatalog
 
catalog = QiskitFunctionsCatalog()
function = catalog.load("qunova/hivqe-chemistry")

Inputs

See the following table for all input parameters the function accepts. The subsequent Molecule options and HI-VQE options sections go into more details about those arguments.

NameTypeDescriptionRequiredDefaultExample
geometryUnion[List[List[Union[str, Tuple[float, float, float]]]], str]This can be either a string or structured lists containing atom and coordinate pairs. If this is given as a string, it must be a molecule geometry in Cartesian Coordinate Format. If this is given as a list, it should be given as a list of lists that each contain an atom string and coordinate tuple.YesN/A[['O', (0, 0, 0)], ['H', (0, 1, 0)], ['H', (0, 0, 1)]] or "O 0 0 0; H 0 1 0; H 0 0 1"
backend_namestrName of the backend to make the query.YesN/Aibm_fez
instancestrThe instance to use in that format.NoOne is randomly picked if your account has access to multiple instances.hub1/group1/project1
max_statesintThe maximum subspace dimension for the diagonalization. Fewer states will be used if the number is not a perfect square.YesN/A100
max_expansion_statesintThe maximum number of classically-generated CI states to be included in each iteration.YesN/A10
molecule_optionsdictOptions related to the molecule used as input to HI-VQE. See the Molecule options section for more details.NoSee the Molecule options section for details.{"basis": "sto3g", "unit": "angstrom" }
hivqe_optionsdictOptions controlling the behavior of the HI-VQE algorithm. See the HI-VQE options section for more details.NoSee the HI-VQE options section for details.{"shots": 10_000, "max_iter": 10 }

Molecule options

The following table details all keys and values that can be set in the molecule_options dictionary, as well as their data types and default values. All keys are optional.

KeyValue typeDefault ValueValid rangeExplanation
"charge"int0VariousAn integer specifying the total net charge of the molecular system. The default value is 0; however, it can be any integer.
"basis"str'sto-3g'VariousA string specifying the basis type; these are passed to pyscf. (eg: "sto-3g", "3-21g", "6-31g", "cc-pvdz")
"active_orbitals"List[int]Every orbital index.The spatial orbital indices valid for the problem.A list of active orbital indices in the interval [0, n) where n is the number of qubits used in the problem. If this is specified, then the frozen_orbitals argument must also be specified.
"frozen_orbitals"List[int]No indices.The spatial orbital indices valid for the problem, excluding active orbitals.A list of frozen orbital indices in the same range as active_orbitals. If specified, then active_orbitals must also be specified. Note that only occupied orbitals should be frozen as the number of active electrons is reduced by 2 for every occupied orbital that is frozen.
"orbital_coeffs"List[List[float]]Hartree-Fock molecular orbitals.Various.The coefficients for the spatial orbitals used in the calculation of the electronic repulsion integrals for the system. Some valid examples are Hartree-Fock molecular orbitals, natural orbitals, and AVAS orbitals.
"symmetry"Union[str, bool]FalseTrue or FalseUsed to invoke point group symmetry for the initial molecular calculations to construct the symmetry adapted orbital basis. These symmetry-adapted orbitals are used as basis functions for the following SCF calculations. The default value is False; if set to True, then it will be invoked and arbitrary point groups will automatically be detected and used. If a particular symmetry is assigned, for example, symmetry = “Dooh”, then an error will be raised if the molecular geometry is not subject to this required symmetry.
"symmetry_subgroup"Optional[str]NoneSee pyscf documentation.Can be used to generate a subgroup of the detected symmetry. This has no effect when symmetry is specified using the symmetry keyword argument.
"unit"str"angstrom"See pyscf documentation.Specifies the measurement unit to use for atomic coordinates and distances. The default is to use angstrom units.
"nucmod"Optional[Union[dict, str]]NoneSee pyscf documentation.Specifies the nuclear model to be used. By default it uses the point nuclear model, and other values enable Gaussian nuclear model. If a function is given, it will be used with the Gaussian nuclear model to generate the nuclear charge distribution value 'zeta'.
"pseudo"Optional[Union[dict, str]]NoneSee pyscf documentation.Specifies the pseudopotential for the atoms in the molecule. This is None by default, indicating that no pseudopotentials are applied and all electrons are explicitly included in the calculations.
"cart"boolFalseSee pyscf documentation.Specifies whether to use cartesian GTOs as the angular momentum basis functions in the calculation. The default value of False will use spherical GTOs.
"magmom"Optional[List[Union[int, float]]]NoneSee pyscf documentation.Sets the colinear spin magnetic moment of each atom. By default, this is None and each atom is initialized with a spin of zero.
"avas_aolabels"Optional[List[str]]Nonei.e. ["H 1s", "O 2p"] for H2OThis defines Atomic Orbital to be included in AVAS scheme. See AVAS documentation .
"avas_threshold"float0.2Between 0.0 and 2.0This specifies the cutoff value used to determine which Atomic Orbitals (AOs) are retained in the active space.
"noons_level"Optional[str]None"mp2" or "ccsd"This defines the theoretical approach for preparing natural orbitals and selecting active orbitals based on the Natural Orbital Occupation Numbers (NOONs) scheme. See NOONs documentation. Both the active and frozen orbital indices must be provided to control the number of orbitals (and the number of qubits).

HI-VQE options

The following table details all keys and values that can be set in the hivqe_options dictionary, as well as their data types and default values. All keys are optional.

KeyValue typeDefault ValueValid rangeExplanation
"shots"int1_000Between 1 and 10 000.Number of shots to use on the quantum device per iteration.
"max_iter"int25Between 1 and 50.The maximum number of iterations to run to optimize the ansatz. The algorithm may use fewer iterations if convergence is achieved early.
"initial_basis_states"List[str]The Hartree-Fock state.Binary strings with the number of bits matching the required number of qubits for the problem.Can be used to restart the algorithm with classical states from a previous result.
"ansatz"str"epa""epa", "hea", or "lucj"This specifies the quantum ansatz to optimize to generate new states. "epa" selects the excitation-preserving ansatz. "hea" selects the hardware-efficient ansatz. "lucj" selects the local unitary cluster Jastrow ansatz.
"convergence_count"int3At least 2.The number of iterations without significant change of the computed energy that should elapse before the algorithm is deemed to have converged.
"convergence_abstol"float1e-4More than 0 and at most 1.The magnitude of change in computed energy that is considered significant for the purposes of convergence checks.
"reset_convergence_count"boolTrueTrue or FalseIf True, the convergence_count iterations must occur without an interrupting significant change to qualify as converging. If False, then the algorithm will stop after convergence_count if insignificant changes have occurred at any iterations during the optimization process.
"configuration_recovery"boolTrueTrue or False.Whether or not to use configuration recovery from the qiskit-addon-sqd package. If True, invalid states sampled from the quantum device are corrected classically. If False, they are discarded.
"ansatz_entanglement"str"circular"Any one of "linear", "reverse_linear", "pairwise", "circular", "full", or "sca". If using the "lucj" ansatz, "lucj_default" is also an option.This specifies the entanglement scheme that should be used within the quantum circuit, following common Qiskit and ffsim conventions for the LUCJ ansatz.
"ansatz_reps"int2Greater than 0.The number of repetitions of each layer in the quantum circuit.
"amplitude_screening_tolerance"Union[float,int]0At least 0, and less than 1.The tolerance for deciding which states should be screened out of the subspace after diagonalization. It specifies the inclusion threshold for the subspace states based on their computed amplitudes.
"overlap_screening_tolerance"float1e-2Between 1e-4 and 1e-1, inclusive.The tolerance for predicting which states should be screened out of the subspace prior to diagonalization. It controls the accuracy of the predicted amplitudes for each state, with a smaller value resulting in more accurate predictions.

Outputs

The function returns a dictionary with four keys and values. The keys and values are documented in the following table:

KeyValue TypeExplanation
"energy"floatThe approximate ground state energy of the molecule.
"states"List[str]The selected determinants that form the subspace used to solve for the energy. They are in alternating alpha-beta format.
"eigenvector"List[float]The eigenvector corresponding to the ground state of the subspace composed of "states".
"energy_variance"floatThe energy variance of the ground state of the subspace composed of "states", giving an indication of the quality of the solution. This value is non-negative and a lower value means that the ground state of the subspace more closely approximates an eigenstate of the system's Hamiltonian.
"energy_history"List[float]The energies computed each iteration during the hybrid optimization process, in the same order that they were computed. Two energies are computed per iteration as part of the SPSA optimization process.

Example

The first example shows how to compute the ground state energy for an NH3 molecule using the HI-VQE algorithm.

Define the molecular geometry and options

The molecular geometry of NH3 is provided with Cartesian coordinates separated with ";" for each atom.

# Define the molecule geometry
geometry = """
N         -0.85188       -0.02741        0.03141;
H          0.16545        0.00593       -0.01648;
H         -1.16348       -0.39357       -0.86702;
H         -1.16348        0.94228        0.06281;
"""

Additional options can be defined and provided for molecular system in the following dictionary format.

# Configure some options for the job.
molecule_options = {"basis": "sto3g"}
hivqe_options = {"shots": 100, "max_iter": 20}

Execute the function with geometry and option inputs.

# Run HI-VQE
job = function.run(
    geometry=geometry,
    backend_name=backend_name,  # e.g. "ibm_fez"
    instance=instance,  # e.g. "ibm-q/open/main"
    max_states=2000,
    max_expansion_states=10,
    molecule_options=molecule_options,
    hivqe_options=hivqe_options,
)

It is a good idea to print the Function job ID so that it can be provided in support requests if something goes wrong.

print("Job ID:", job.job_id)

This example then utilizes 16 qubits with 8 orbitals of sto3g basis for an NH3 molecule.

Check your Qiskit Function workload's status or return results as follows:

print(job.status())

After the job is completed, the results can be obtained with result() instance.

result = job.result()
print(result)

Output:

{
    "energy": np.float64(-55.521064587741876),
    "eigenvector": array(
        [
            9.82446681e-01,
            9.53706109e-03,
            3.09707825e-06,
            ...,
            -1.79658131e-07,
            3.41576228e-09,
            1.58456937e-03,
        ]
    ),
    "states": [
        "1111111111000000",
        "1111111110010000",
        "1111111011010000",
        "...",
        "1100011011001111",
        "1001011011001111",
        "1100001111001111",
    ],
}

To access the ground state energy, use the "energy" key. The "eigenvector" key provides the CI coefficients with corresponding bitstring notation of electron configuration stored with "states" of the results.

fci_energy = -55.521148034704126  # the exact energy using FCI method
hivqe_energy = result["energy"]
print(
    f"|Exact Energy - HI-VQE Energy|: {abs(fci_energy-hivqe_energy)*1000} mHa"
)
print(f"Sampled Number of States: {len(result["states"])}")

Output:

|Exact Energy - HI-VQE Energy|: 0.077237504 mHa Sampled Number of States: 1936


Performance

This section shows the demonstrated benchmark calculations of HI-VQE with a 24-qubit case for Li2S, a 40-qubit case for an N2 molecule, and a 44-qubit case for an FeP-NO system.

Dissociation potential energy surface curve for an Li2S molecule with 24 qubits

The PES curve is shown with the FCI reference and initial guess from RHF, together with the energy error from the FCI reference.

Image showing that HI-VQE produces solutions within chemical accuracy of a classical reference PES curve for the Li2S system.

The calculations have been conducted with the following geometries and options.

# Define Li2S geometries
Li2S_geoms = {
    "Li2S_1.51": "S        -1.239044    0.671232   -0.030374;Li       -1.506327    0.432403   -1.498949;Li       -0.899996    0.973348    1.826768;",
    "Li2S_2.40": "S        -1.741432    0.680397    0.346702;Li       -0.529307    0.488006   -1.729343;Li       -1.284307    0.989409    2.177209;",
    "Li2S_3.80": "S        -2.707255    0.674298    0.909161;Li        0.079218    0.552012   -1.671656;Li       -0.927010    0.931502    1.557063;",
}
 
# Configure some options for the job.
molecule_options = {
    "basis": "sto3g",
}
hivqe_options = {
    "shots": 100,
    "max_iter": 20,
}
 
results = []
for geom in ["Li2S_1.51", "Li2S_2.40", "Li2S_3.80"]:
    # Run HI-VQE
    job = function.run(
        geometry=Li2S_geoms[geom],
        backend_name=backend_name,  # e.g. "ibm_fez"
        instance=instance,  # e.g. "ibm-q/open/main"
        max_states=2000,
        max_expansion_states=10,
        molecule_options=molecule_options,
        hivqe_options=hivqe_options,
    )
    results.append(job.result())

The red dots represent the HI-VQE calculation results for six different geometries, and three geometries corresponding to 1.51, 2.40, and 3.80 Angstrom are provided as input in the above cell.

Dissociation PES curve for an N2 molecule with 40 qubits

The nitrogen molecule has been identified as a multireference system with large correlation energy contributions beyond the Hartree-Fock state. We conducted a benchmark calculation for the N2 molecule with cc-pvdz basis, (20o,14e) using the homo-lumo active orbital selection. The complete active space (CAS) number to represent this problem is 6,009,350,400. It is not possible to obtain the eigenvalue problem solution (for energy and electronic structure) with this number of states using a powerful desktop (16cpu/64GB). With HI-VQE, users can efficiently search the subspace of CAS states to find chemically accurate results while saving computation resources significantly. The following plots show the PES curve of 40 qubits HI-VQE calculation of the N2 molecule dissociation.

Image showing that HI-VQE produces solutions within chemical accuracy of a classical reference PES curve for the N2 system.

Dissociation PES curve for five-coordinated iron(II)-porphyrin with an NO system with 44 qubits

Another interesting chemical system is an iron(II)-porphyrin (FeP) complex with a coordinated nitric oxide (NO) ligand, which represents a biologically relevant metalloporphyrin system that plays crucial roles in various physiological processes. In this example, HI-VQE has been utilized to estimate the accurate potential energy surface curve of the intermolecular interaction between FeP and NO (ground state energy for differently separated geometries). The combined system has 450 orbitals and 202 electrons (450o,202e) with 6-31g(d) basis in total. The homo-lumo active orbital selection was utilized to calculate the smaller case from the real case with (22o,22e). From the following benchmark results, we were able to achieve the chemical accuracy (> 1.6 mHa) with a state-of-the-art classical computer chemistry calculation of CASCI(DMRG) (22o,22e) reference.

Image showing that HI-VQE produces solutions within chemical accuracy of a classical reference PES curve for the FeP-NO system.

Benchmarks

  • Exact matrix size is the number of determinants for exact solution, such as FCI and CASCI.
  • HI-VQE calculation samples and calculates the subspace of it (as in, HI-VQE matrix size).
  • Total time includes QPU runtime and Qiskit Function runs with CPU.
  • Accuracy is estimated from the energy difference from exact solution.
Chemical systemNumber of qubitsExact matrix sizeHI-VQE matrix sizeE(diff) from exact (mHa)Number of iterationTotal timeQPU runtime usage
NH3NH_3 (8o,10e)16313619360.08637 s34 s
Li2SLi_2S (10o,10e)206350439690.605250 s50 s
NH3NH_3 (15o,10e)309018009497290.905354 s54 s
N2N_2 (16o,14e)3213087360017982811.1096531 s121 s
3H2O3H_2O (18o,24e)363446220963994240.90245174 s130 s
N2N_2 (20o,14e)40600935040090120041.202146547 s258 s

Fetch error messages

If your workload status is ERROR, use job.result() to fetch the error message to help debug as follows:

job = function.run(
    geometry=geometry,
    backend_name=backend.name,
    max_states=2000,
    max_expansion_states=15,
    molecule_options=molecule_options,
    hivqe_options=hivqe_options,
)
 
result = job.result()
if job.status() == "ERROR":
    print("Status:", result["status"])
    print("Message:", result["message"])

Get support

You can send an email to qiskit.support@qunovacomputing.com for help with this function.

If you want help with troubleshooting a specific error, please provide the Function job ID of the job that encountered the error.


Next steps

Recommendations
Was this page helpful?
Report a bug or request content on GitHub.