--- title: Qunova HI-VQE Chemistry API reference description: API reference for HI-VQE Chemistry by Qunova Computing source: https://quantum.cloud.ibm.com/docs/en/functions/qunova-chemistry/api-reference --- # 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` 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, 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` Type: `` `str` `` The name of an FCIDUMP file you [uploaded](/docs/managed-workflows/manage-files-across-managed-workflows) 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](/docs/functions/qunova-chemistry/get-started#example-run-from-an-fcidump-file). - Required: Yes, unless `geometry` is given - Example: `"nh3.FCIDUMP"` ### `backend_name` Type: `` `str` `` Name of the IBM Quantum backend the function runs its quantum jobs on. - 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. It also decides, with the number of qubits, the [function size](#function_size) the run needs. - Required: Yes - Valid range: Between 1 and 400,000,000 - Example: `100` ### `max_expansion_states` Type: `` `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` 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: Any integer #### `basis` Type: `` `Union[str, dict]` `` 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"`. A dictionary gives a basis for each element, as in PySCF, for example `{"O": "cc-pvdz", "H": "sto-3g"}`. - 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 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` 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, each at most once #### `orbital_coeffs` Type: `` `Union[List[List[float]], numpy.ndarray]` `` 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. 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` 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, `"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` 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](https://pyscf.org/pyscf_api_docs/pyscf.gto.html#pyscf.gto.mole.MoleBase.build) #### `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](https://pyscf.org/pyscf_api_docs/pyscf.gto.html#pyscf.gto.mole.MoleBase.build) #### `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. - Valid range: See [PySCF documentation](https://pyscf.org/pyscf_api_docs/pyscf.gto.html#pyscf.gto.mole.MoleBase.build) #### `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](https://pyscf.org/pyscf_api_docs/pyscf.gto.html#pyscf.gto.mole.MoleBase.build) #### `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](https://pyscf.org/pyscf_api_docs/pyscf.gto.html#pyscf.gto.mole.MoleBase.build) #### `magmom` Type: `` `Optional[List[Union[int, float]]]` `` Default value: `` `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](https://pyscf.org/pyscf_api_docs/pyscf.gto.html#pyscf.gto.mole.MoleBase.build) #### `avas_aolabels` Type: `` `Optional[List[str]]` `` Default value: `` `None` `` This defines Atomic Orbital to be included in AVAS scheme. See [AVAS documentation](https://arxiv.org/abs/1701.07862). - Valid range: Atomic orbital labels, e.g., \["H 1s", "O 2p"] for H$_2$O, each label at most once #### `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. #### `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](https://doi.org/10.1063/5.0042147). 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. - Valid range: 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`](/docs/api/qiskit-addon-sqd/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](https://qiskit-community.github.io/ffsim/how-to-guides/qiskit-lucj.html). - 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 }` ### `use_session` Type: `` `bool` `` Default value: `` `False` `` Runs the function's quantum jobs in one [Qiskit Runtime session](/docs/ibm-quantum-compute/run-jobs-session), instead of as separate jobs. - Required: No - Example: `True` ### `function_size` Type: `` `str` `` Default value: `` `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](/docs/functions/qunova-chemistry/get-started#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](/docs/functions/qunova-chemistry/get-started#results-of-a-stopped-job).