HI-VQE Chemistry API reference

Qiskit Functions
Qiskit Functions — pre-built tools created by partner organizations — abstract away parts of the software development workflow to simplify and accelerate utility-scale algorithm discovery and application development. Click to view the guide for this Qiskit Function.
HI-VQE Chemistry Qiskit Function guide

Inputs

`geometry`

Type: `Union[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.

Required: Yes
Example: [['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_name`

Type: `str`

Name of the backend to make the query.

Required: Yes
Example: ibm_fez

`max_states`

Type: `int`

The maximum subspace dimension for the diagonalization. Fewer states will be used if the number is not a perfect square.

Required: Yes
Example: 100

`max_expansion_states`

Type: `int`

The maximum number of classically-generated CI states to be included in each iteration.

Required: Yes
Example: 10

`molecule_options`

Type: `dict`

Options related to the molecule used as input to HI-VQE. The following list 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.

`charge`

Type: `int`

Default value: `0`

An integer specifying the total net charge of the molecular system. The default value is 0; however, it can be any integer.

Valid range: Various

`basis`

Type: `str`

Default value: `'sto-3g'`

A string specifying the basis type; these are passed to pyscf. For example: "sto-3g", "3-21g", "6-31g", "cc-pvdz"

Valid range: Various

`active_orbitals`

Type: `List[int]`

Default value: Every orbital index

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.

Valid range: The spatial orbital indices valid for the problem

`frozen_orbitals`

Type: `List[int]`

Default value: `No indices`

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.

Valid range: The spatial orbital indices valid for the problem, excluding active orbitals

`orbital_coeffs`

Type: `List[List[float]]`

Default value: `Hartree-Fock molecular orbitals`

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.

Valid range: Various

`symmetry`

Type: `Union[str, bool]`

Default value: `False`

Used 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.

Valid range: True or False

`symmetry_subgroup`

Type: `Optional[str]`

Default value: `None`

Can be used to generate a subgroup of the detected symmetry. This has no effect when symmetry is specified using the symmetry keyword argument.

Valid range: See pyscf documentation

`unit`

Type: `str`

Default value: `angstrom`

Specifies the measurement unit to use for atomic coordinates and distances. The default is to use angstrom units.

Valid range: See pyscf documentation

`nucmod`

Type: `Optional[Union[dict, str]]`

Default value: `None`

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'.

Valid range: See pyscf documentation

`pseudo`

Type: `Optional[Union[dict, str]]`

Default value: `None`

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.

Valid range: See pyscf documentation

`cart`

Type: `bool`

Default value: `False`

Specifies whether to use cartesian GTOs as the angular momentum basis functions in the calculation. The default value of False will use spherical GTOs.

Valid range: See pyscf documentation

`magmom`

Type: `(`Optional[List[Union[int, float]]]`

Default value: `1_000`

Sets the colinear spin magnetic moment of each atom. By default, this is None and each atom is initialized with a spin of zero.

Valid range: See pyscf documentation

`avas_aolabels`

Type: `Optional[List[str]]`

Default value: `None`

This defines Atomic Orbital to be included in AVAS scheme. See AVAS documentation.

Valid range: i.e., ["H 1s", "O 2p"] for H $_2$ O

`avas_threshold`

Type: `float`

Default value: `0.2`

This specifies the cutoff value used to determine which Atomic Orbitals (AOs) are retained in the active space.

Valid range: Between 0.0 and 2.0

`noons_level`

Type: `Optional[str]`

Default value: `None`

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).

Valid range: "mp2" or "ccsd"

Required: No
Example: {"basis": "sto3g", "unit": "angstrom" }

`hivqe_options`

Type: `dict`

Options controlling the behavior of the HI-VQE algorithm. The following list 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.

`shots`

Type: `int`

Default value: `1_000`

Number of shots to use on the quantum device per iteration.

Valid range: Between 1 and 10 000

`max_iter`

Type: `int`

Default value: `25`

The maximum number of iterations to run to optimize the ansatz. The algorithm may use fewer iterations if convergence is achieved early.

Valid range: Between 1 and 50

`initial_basis_states`

Type: `List[str]`

Default value: The Hartree-Fock state

Can be used to restart the algorithm with classical states from a previous result.

Valid range: Binary strings with the number of bits matching the required number of qubits for the problem.

`ansatz`

Type: `str`

Default value: `epa`

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.

Valid range: "epa", "hea", or "lucj"

`convergence_count`

Type: `int`

Default value: `3`

The number of iterations without significant change of the computed energy that should elapse before the algorithm is deemed to have converged.

At least 2

`convergence_abstol`

Type: `float`

Default value: `1e-4`

The magnitude of change in computed energy that is considered significant for the purposes of convergence checks.

Valid range: More than 0 and at most 1

`reset_convergence_count`

Type: `bool`

Default value: `True`

If 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.

Valid range: True or False

`configuration_recovery`

Type: `bool`

Default value: `True`

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.

Valid range: True or False

`ansatz_entanglement`

Type: `str`

Default value: `circular`

This specifies the entanglement scheme that should be used within the quantum circuit, following common Qiskit and ffsim conventions for the LUCJ ansatz.

Valid range: Any one of "linear", "reverse_linear", "pairwise", "circular", "full", or "sca". If using the "lucj" ansatz, "lucj_default" is also an option.

`ansatz_reps`

Type: `int`

Default value: `2`

The number of repetitions of each layer in the quantum circuit.

Valid range: Greater than 0

`amplitude_screening_tolerance`

Type: `Union[float,int]`

Default value: `0`

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.

Valid range: At least 0, and less than 1

`overlap_screening_tolerance`

Type: `float`

Default value: `1e-2`

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.

Valid range: Between 1e-4 and 1e-1, inclusive

Required: No
Example: {"shots": 10_000, "max_iter": 10 }

Outputs

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

Key	Value Type	Explanation
`"energy"`	`float`	The 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"`	`float`	The 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.

Was this page helpful?

Report a bug, typo, or request content on GitHub.