Skip to content

[Review before IBM] HI-VQE docs for the 4.0.0 function #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
seihyun-jeong wants to merge 3 commits into from
Closed

[Review before IBM] HI-VQE docs for the 4.0.0 function #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
afbedf0
Update the HI-VQE docs for the 4.0.0 function
seihyun-jeong Oct 7, 2026
e20928a
Save the HI-VQE results file under its own name before opening it
seihyun-jeong Oct 7, 2026
de8f74b
Let the HI-VQE licence example run on the reader's own backend
seihyun-jeong Oct 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions docs/api/functions/qunova-chemistry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,7 +234,6 @@ The function returns a dictionary with four keys and values. The 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. |
| `"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. |
94 changes: 82 additions & 12 deletions docs/guides/qunova-chemistry.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
"---\n",
"\n",
"\n",
"{/* cspell:ignore lumo hivqe DMRG ccsd, ffsim, pvdz, Qunova, HI-VQE, AVAS, Dooh, pyscf, nucmod, GTO's, lucj, pseudopotential, pseudopotentials, magmom, Jastrow, multireference, Pellow, Jarman */}"
"{/* cspell:ignore asstr lumo hivqe DMRG ccsd, ffsim, pvdz, Qunova, HI-VQE, AVAS, Dooh, pyscf, nucmod, GTO's, lucj, pseudopotential, pseudopotentials, magmom, Jastrow, multireference, Pellow, Jarman */}"
]
},
{
Expand Down Expand Up @@ -348,7 +348,7 @@
"name": "stdout",
"output_type": "stream",
"text": [
"{'eigenvector': [0.9824448589364075, 0.009527106392132133, 6.854074372058527e-08, 3.591500190038039e-07, 0.0012975231577544268, 2.310159709002111e-05, ...], 'energy': -55.52108557170985, 'energy_history': [-55.51901898989887, -55.52056881448526, -55.52065046778772, -55.520690696813716, -55.520691108428, -55.520708448092634, ...], 'energy_variance': 3.066239097617371e-10, ...}\n"
"{'energy': -55.52108557170985, 'energy_history': [-55.51901898989887, -55.52056881448526, -55.52065046778772, -55.520690696813716, -55.520691108428, -55.520708448092634, ...], 'energy_variance': 3.066239097617371e-10, 'results_file_name': '20260914_105...vqe_result.h5'}\n"
]
}
],
Expand All @@ -365,7 +365,14 @@
"id": "2b6fb05c",
"metadata": {},
"source": [
"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."
"To access the ground state energy, use the `\"energy\"` key. The `\"results_file_name\"` key provides the name of the h5 results file that can be downloaded using `QiskitServerless`.\n",
"\n",
"This file contains :\n",
"- `\"final_energy\"`: the energy of the final trial state,\n",
"- `\"final_energy_variance\"`: the energy variance of the final trial state,\n",
"- `\"energy_history\"`: the energy history over HI-VQE's training,\n",
"- `\"eigenvector\"`: the CI coefficients of the final trial state's wave function, and\n",
"- `\"states\"`: the corresponding electron configurations comprising the final trial state wave function."
]
},
{
Expand All @@ -378,8 +385,7 @@
"name": "stdout",
"output_type": "stream",
"text": [
"|Exact Energy - HI-VQE Energy|: 0.06246299427914437 mHa\n",
"Sampled Number of States: 1936\n"
"|Exact Energy - HI-VQE Energy|: 0.06246299427914437 mHa\n"
]
}
],
Expand All @@ -389,8 +395,63 @@
"print(\n",
" f\"|Exact Energy - HI-VQE Energy|: \"\n",
" f\"{abs(fci_energy - hivqe_energy) * 1000} mHa\"\n",
")"
]
},
{
"cell_type": "markdown",
"id": "03b51be7",
"metadata": {},
"source": [
"To download the results file for the calculation, you will need to create a `QiskitServerless` instance using the same credentials as `QiskitFunctionCatalog`."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "fbe0d8f6",
"metadata": {},
"outputs": [],
"source": [
"from qiskit_ibm_catalog import QiskitServerless\n",
"\n",
"serverless = QiskitServerless(\n",
" channel=\"ibm_quantum_platform\",\n",
" instance=\"INSTANCE_CRN\",\n",
" token=\"YOUR_API_KEY\",\n",
")"
]
},
{
"cell_type": "markdown",
"id": "0a081159",
"metadata": {},
"source": [
"The file can then be downloaded to the current directory and opened as shown below. Reading it requires the `h5py` package, which you can install with `pip install h5py`."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0ea7cacc",
"metadata": {},
"outputs": [],
"source": [
"import h5py\n",
"\n",
"# Save the file in the current directory under its own name\n",
"results_file_name = result[\"results_file_name\"]\n",
"serverless.file_download(\n",
" results_file_name, function, target_name=results_file_name\n",
")\n",
"print(f\"Sampled Number of States: {len(result['states'])}\")"
"\n",
"# Read data from the results file for a single calculation\n",
"with h5py.File(results_file_name, \"r\") as f:\n",
" states = f[\"states\"].asstr()[:]\n",
" eigenvector = f[\"eigenvector\"][:]\n",
" energy_history = f[\"energy_history\"][:]\n",
" final_energy = f[\"final_energy\"][0]\n",
" final_energy_variance = f[\"final_energy_variance\"][0]"
]
},
{
Expand Down Expand Up @@ -422,11 +483,7 @@
"from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
"from hivqe_qiskit_function_utils import FunctionWrapper\n",
"\n",
"catalog = QiskitFunctionsCatalog(\n",
" token=\"your_qiskit_functions_catalog_token\",\n",
" channel=\"ibm_quantum_platform\",\n",
" instance=\"your_ibm_instance\",\n",
")\n",
"catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n",
"\n",
"molecule_geometry = f\"\"\"\n",
"O 0 0 0;\n",
Expand All @@ -440,7 +497,7 @@
")\n",
"job = hivqe.run(\n",
" geometry=molecule_geometry,\n",
" backend_name=\"ibm_torino\",\n",
" backend_name=backend_name, # can use any device with at least 14 qubits\n",
" max_states=10000,\n",
" max_expansion_states=1000,\n",
" hivqe_options={\"ansatz\": \"epa\", \"max_iter\": 10},\n",
Expand Down Expand Up @@ -649,6 +706,19 @@
"job.status()"
]
},
{
"cell_type": "markdown",
"id": "7c1e4a2b",
"metadata": {},
"source": [
"## Changelog\n",
"\n",
"### 4.0.0\n",
"\n",
"- The result no longer includes `\"states\"` or `\"eigenvector\"`. They are now saved in an HDF5 results file, together with `\"final_energy\"`, `\"final_energy_variance\"`, and `\"energy_history\"`.\n",
"- Added `\"results_file_name\"` to the result. It gives the name of the results file, which you can download with `serverless.file_download()`. Reading the file requires the `h5py` package. See the [Example](#example) section for how to download and read it."
]
},
{
"cell_type": "markdown",
"id": "e9ec2e67",
Expand Down
79 changes: 77 additions & 2 deletions docs/tutorials/qunova-hivqe.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
"---\n",
"\n",
"\n",
"{/* cspell:ignore fontsize labelsize DMRG hivqe mcscf CASCI */}\n",
"{/* cspell:ignore asstr fontsize labelsize DMRG hivqe mcscf CASCI */}\n",
"\n",
"# Dissociation PES curves with Qunova HiVQE"
]
Expand Down Expand Up @@ -62,7 +62,7 @@
"outputs": [],
"source": [
"!pip install --upgrade pip\n",
"!pip install -U qiskit-ibm-catalog \"qiskit_ibm_runtime<0.42.0\" pyscf numpy matplotlib typing_extensions"
"!pip install -U qiskit-ibm-catalog \"qiskit_ibm_runtime<0.42.0\" pyscf numpy matplotlib typing_extensions h5py"
]
},
{
Expand Down Expand Up @@ -99,6 +99,30 @@
"hivqe = catalog.load(\"qunova/hivqe-chemistry\")"
]
},
{
"cell_type": "markdown",
"id": "00c68174",
"metadata": {},
"source": [
"You will also need to create a `QiskitServerless` instance to download the results file for the calculation. This uses the same credentials as `QiskitFunctionCatalog`."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2a0687f2",
"metadata": {},
"outputs": [],
"source": [
"from qiskit_ibm_catalog import QiskitServerless\n",
"\n",
"serverless = QiskitServerless(\n",
" channel=\"ibm_quantum_platform\",\n",
" instance=\"INSTANCE_CRN\",\n",
" token=\"YOUR_API_KEY\",\n",
")"
]
},
{
"attachments": {},
"cell_type": "markdown",
Expand Down Expand Up @@ -326,6 +350,57 @@
"pprint.pprint(hivqe_result)"
]
},
{
"cell_type": "markdown",
"id": "51a9e47b",
"metadata": {},
"source": [
"The results file for each of the calculations can be downloaded into the current directory using `QiskitServerless`. These files contain `\"states\"`, `\"eigenvector\"`, `\"energy_history\"`, `\"final_energy\"`, and `\"final_energy_variance\"`."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "025c97ce",
"metadata": {},
"outputs": [],
"source": [
"if len(info_jobid) == completed_jobs_num:\n",
" print(\"All jobs are completed\")\n",
" for i, job in enumerate(completed_jobs.items()):\n",
" dis, cal = job\n",
" print(dis, cal.result()[\"results_file_name\"])\n",
" serverless.file_download(cal.result()[\"results_file_name\"], hivqe)"
]
},
{
"cell_type": "markdown",
"id": "7aee79ec",
"metadata": {},
"source": [
"The results can be read from the h5 file as follows:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "058f92b1",
"metadata": {},
"outputs": [],
"source": [
"import h5py\n",
"\n",
"results_file_name = \"PATH_TO_DOWNLOADED_RESULTS_FILE\"\n",
"\n",
"# Read data from the results file for a single calculation\n",
"with h5py.File(results_file_name, \"r\") as f:\n",
" states = f[\"states\"].asstr()[:]\n",
" eigenvector = f[\"eigenvector\"][:]\n",
" energy_history = f[\"energy_history\"][:]\n",
" final_energy = f[\"final_energy\"][0]\n",
" final_energy_variance = f[\"final_energy_variance\"][0]"
]
},
{
"cell_type": "markdown",
"id": "cc7c2793",
Expand Down