[Review before IBM] HI-VQE docs for 5.0.x (up to 5.0.8)

docs/api/functions/qunova-chemistry.mdx

@@ -16,13 +16,26 @@ description: API reference for HI-VQE Chemistry, a Qiskit Function by Qunova Com
 
 ## 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, and
+nothing is billed. `function.validate_arguments({...})` runs the same check without
+running anything, and `function.arguments_schema` lists every argument with its
+type, range and default.
+
 ### `geometry`
 <Attribute attributeTypeHint="`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
+- 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"`
 </Attribute>
 
+### `fcidump_file_name`
+<Attribute attributeTypeHint="`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](/docs/guides/qunova-chemistry#run-from-an-fcidump-file).
+- Required: Yes, unless `geometry` is given
+- Example: `"nh3.FCIDUMP"`
+</Attribute>
+
 ### `backend_name`
 <Attribute attributeTypeHint="`str`">
 Name of the backend to make the query.
@@ -34,13 +47,15 @@ Name of the backend to make the query.
 <Attribute attributeTypeHint="`int`">
 The maximum subspace dimension for the diagonalization. Fewer states will be used if the number is not a perfect square.
 - Required: Yes
+- Valid range: Between 1 and 400 000 000
 - Example: `100`
 </Attribute>
 
 ### `max_expansion_states`
 <Attribute attributeTypeHint="`int`">
 The maximum number of classically-generated CI states to be included in each iteration.
 - Required: Yes
+- Valid range: At least 1
 - Example: `10`
 </Attribute>
 
@@ -63,19 +78,19 @@ A string specifying the basis type; these are passed to pyscf. For example: `"st
 
 #### `active_orbitals`
 <Attribute attributeTypeHint="`List[int]`" attributeValue="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
+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
 </Attribute>
 
 #### `frozen_orbitals`
 <Attribute attributeTypeHint="`List[int]`" attributeValue="`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
+- Valid range: The spatial orbital indices valid for the problem, excluding active orbitals, each at most once
 </Attribute>
 
 #### `orbital_coeffs`
-<Attribute attributeTypeHint="`List[List[float]]`" attributeValue="`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. 
+<Attribute attributeTypeHint="`Union[List[List[float]], numpy.ndarray]`" attributeValue="`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
 </Attribute>
 
@@ -116,21 +131,20 @@ Specifies whether to use cartesian GTOs as the angular momentum basis functions
 </Attribute>
 
 #### `magmom`
-<Attribute attributeTypeHint="`(`Optional[List[Union[int, float]]]`" attributeValue="`1_000`">
+<Attribute attributeTypeHint="`Optional[List[Union[int, float]]]`" attributeValue="`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)
 </Attribute>
 
 #### `avas_aolabels`
 <Attribute attributeTypeHint="`Optional[List[str]]`" attributeValue="`None`">
 This defines Atomic Orbital to be included in AVAS scheme. See [AVAS documentation](https://arxiv.org/abs/1701.07862).
-- Valid range: i.e., ["H 1s", "O 2p"] for H$_2$O
+- Valid range: i.e., ["H 1s", "O 2p"] for H$_2$O, each label at most once
 </Attribute>
 
 #### `avas_threshold`
 <Attribute attributeTypeHint="`float`" attributeValue="`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
 </Attribute>
 
 #### `noons_level`
@@ -224,17 +238,53 @@ The tolerance for predicting which states should be screened out of the subspace
 - Example: `{"shots": 10_000, "max_iter": 10 }`
 </Attribute>
 
-
-
+### `use_session`
+<Attribute attributeTypeHint="`bool`" attributeValue="`False`">
+Runs the function's quantum jobs in one Qiskit Runtime session, so that jobs
+after the first do not wait in the queue again.
+- Required: No
+- Example: `True`
+</Attribute>
+
+### `function_size`
+<Attribute attributeTypeHint="`str`" attributeValue="`m`">
+Which resources the job runs on, and what the run is billed. 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 | 8 CPUs, 32 GB |
+| `"m"` | Up to 48 | Up to 10,000,000 | 16 CPUs, 128 GB |
+| `"l"` | More than 48 | More than 10,000,000 | 48 CPUs, 768 GB |
+
+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 1221 naming the size to use; the rejected run is
+still billed at the size it was submitted at. A size larger than it needs runs,
+and is billed at that larger size. To check the size before submitting, see
+[Size your problem needs](/docs/guides/qunova-chemistry#size-your-problem-needs).
+Licensed runs are checked the same way, and the size sets their compute, and so
+their classical compute cost, but no per-execution fee is charged. Runs with
+trial access are limited to `"s"`, and are rejected with error code 4500 above
+it.
+- Required: No
+- Example: `"l"`
+</Attribute>
 
 ## Outputs
 
-The function returns a dictionary with four keys and values. The keys and values are documented in the following table:
+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. |
-| `"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. |
+| `"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/guides/qunova-chemistry#results-of-a-stopped-job).