diff --git a/docs/api/functions/qunova-chemistry.mdx b/docs/api/functions/qunova-chemistry.mdx index 773d70af0260..cf2cc742652e 100644 --- a/docs/api/functions/qunova-chemistry.mdx +++ b/docs/api/functions/qunova-chemistry.mdx @@ -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. | \ No newline at end of file diff --git a/docs/guides/qunova-chemistry.ipynb b/docs/guides/qunova-chemistry.ipynb index 1807b90fe9e0..11f3dc2dcda4 100644 --- a/docs/guides/qunova-chemistry.ipynb +++ b/docs/guides/qunova-chemistry.ipynb @@ -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 */}" ] }, { @@ -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" ] } ], @@ -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." ] }, { @@ -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" ] } ], @@ -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]" ] }, { @@ -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", @@ -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", @@ -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", diff --git a/docs/tutorials/qunova-hivqe.ipynb b/docs/tutorials/qunova-hivqe.ipynb index 76a0638d1faa..da02a45ce223 100644 --- a/docs/tutorials/qunova-hivqe.ipynb +++ b/docs/tutorials/qunova-hivqe.ipynb @@ -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" ] @@ -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" ] }, { @@ -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", @@ -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",