Qunova HI-VQE Chemistry API reference

Inputs

Arguments are checked when you call run(), before a job is created: one with the wrong name, type or range raises an exception describing what failed. function.validate_arguments({...}) runs the same check without running anything, and function.arguments_schema lists every argument with its type, range and default.

`geometry`

タイプ: `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, unless fcidump_file_name is given
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"

`fcidump_file_name`

タイプ: `str`

The name of an FCIDUMP file you uploaded to the function with file_upload, without a directory part, to use in place of geometry. The integrals of the file are used as they are, and geometry and molecule_options are ignored. The file can be plain text or gzip-compressed, and must describe a closed-shell singlet. See Run from an FCIDUMP file.

Required: Yes, unless geometry is given
Example: "nh3.FCIDUMP"

`backend_name`

タイプ: `str`

Name of the IBM Quantum backend the function runs its quantum jobs on.

Required: Yes
Example: "ibm_fez"

`max_states`

タイプ: `int`

The maximum subspace dimension for the diagonalization. Fewer states will be used if the number is not a perfect square. It also decides, with the number of qubits, the function size the run needs.

Required: Yes
Valid range: Between 1 and 400,000,000
Example: 100

`max_expansion_states`

タイプ: `int`

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

Required: Yes
Valid range: At least 1, and at most max_states
Example: 10

`molecule_options`

タイプ: `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`

タイプ: `int`

デフォルト値: `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: Any integer

`basis`

タイプ: `Union[str, dict]`

デフォルト値: `'sto-3g'`

A string specifying the basis type; these are passed to PySCF. For example: "sto-3g", "3-21g", "6-31g", "cc-pvdz". A dictionary gives a basis for each element, as in PySCF, for example {"O": "cc-pvdz", "H": "sto-3g"}.

Valid range: Various

`active_orbitals`

タイプ: `List[int]`

デフォルト値: Every orbital index

A list of active orbital indices in the interval [0, n) where n is the number of orbitals in the basis. If this is specified, then the frozen_orbitals argument must also be specified.

Valid range: The spatial orbital indices valid for the problem, each at most once

`frozen_orbitals`

タイプ: `List[int]`

デフォルト値: `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, each at most once

`orbital_coeffs`

タイプ: `Union[List[List[float]], numpy.ndarray]`

デフォルト値: `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. Give a matrix as a list of equal-length rows or as a 2-D NumPy array, such as PySCF's mo_coeff.

Valid range: Various

`symmetry`

タイプ: `Union[str, bool]`

デフォルト値: `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, "Dooh", then an error will be raised if the molecular geometry is not subject to this required symmetry.

Valid range: True, False, or a point group name such as "Dooh"

`symmetry_subgroup`

タイプ: `Optional[str]`

デフォルト値: `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`

タイプ: `str`

デフォルト値: `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`

タイプ: `Optional[Union[dict, str]]`

デフォルト値: `None`

Specifies the nuclear model to be used. By default it uses the point nuclear model, and other values enable Gaussian nuclear model.

Valid range: See PySCF documentation

`pseudo`

タイプ: `Optional[Union[dict, str]]`

デフォルト値: `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`

タイプ: `bool`

デフォルト値: `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`

タイプ: `Optional[List[Union[int, float]]]`

デフォルト値: `None`

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`

タイプ: `Optional[List[str]]`

デフォルト値: `None`

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

Valid range: Atomic orbital labels, e.g., ["H 1s", "O 2p"] for H $_2$ O, each label at most once

`avas_threshold`

タイプ: `float`

デフォルト値: `0.2`

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

`noons_level`

タイプ: `Optional[str]`

デフォルト値: `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`

タイプ: `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`

タイプ: `int`

デフォルト値: `1_000`

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

Valid range: Between 1 and 10 000

`max_iter`

タイプ: `int`

デフォルト値: `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`

タイプ: `List[str]`

デフォルト値: 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`

タイプ: `str`

デフォルト値: `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`

タイプ: `int`

デフォルト値: `3`

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

Valid range: At least 2

`convergence_abstol`

タイプ: `float`

デフォルト値: `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`

タイプ: `bool`

デフォルト値: `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`

タイプ: `bool`

デフォルト値: `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`

タイプ: `str`

デフォルト値: `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`

タイプ: `int`

デフォルト値: `2`

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

Valid range: Greater than 0

`amplitude_screening_tolerance`

タイプ: `Union[float,int]`

デフォルト値: `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`

タイプ: `float`

デフォルト値: `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 }

`use_session`

タイプ: `bool`

デフォルト値: `False`

Runs the function's quantum jobs in one Qiskit Runtime session, instead of as separate jobs.

Required: No
Example: True

`function_size`

タイプ: `str`

デフォルト値: `M`

The compute profile the job runs on. It is passed to run() like the arguments above, though it belongs to the platform rather than to this function.

`function_size`	Qubits	`max_states`	Compute profile
`"S"`	Up to 20	Up to 1,000	`8x32`
`"M"`	Up to 48	Up to 10,000,000	`16x128`
`"L"`	More than 48	More than 10,000,000	`48x768`

A problem needs the smallest size that fits both its qubits and its max_states. A size smaller than the problem needs is rejected before any QPU time is spent, with error code 4600 naming the size to use. A size larger than it needs runs on the larger compute profile, and records a 4601 advisory event. Runs with trial access are limited to "S", and are rejected with error code 4500 above it. To calculate the size before submitting, see Function sizes.

Required: No
Example: "L"

Outputs

The function returns a dictionary with the following keys and values:

Key	Value Type	Explanation
`"energy"`	`float`	The approximate ground state energy of the molecule.
`"results_file_name"`	`string`	The name of the hdf5 results file that can be downloaded using Qiskit Serverless. The file contains `"states"`, `"eigenvector"`, `"energy_history"`, `"final_energy"`, and `"final_energy_variance"`.
`"energy_variance"`	`float`	The energy variance of the ground state of the subspace composed of the `"states"` saved in the results file, 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.
`"function_version"`	`string`	The version of the function that ran the job. Quote it in a support request.
`"metadata"`	`dict`	Contains `"resource_usage"`, giving the time spent in each stage of the job, including QPU time.

A job stopped with job.cancel() returns what the run had computed by then instead, with "status": "canceled", and writes no results file. See Results of a stopped job.

このページは役に立ちましたか？

バグや誤字の報告、またはコンテンツの要求はGitHubで行ってください。