Repository navigation
[Review before IBM] HI-VQE docs for 5.0.x (up to 5.0.8) - #14
Open
seihyun-jeong wants to merge 41 commits into
Open
seihyun-jeong wants to merge 41 commits into
seihyun-jeong wants to merge 41 commits into
Conversation
In 4.0.0 the result no longer carries "states" or "eigenvector". They are written to an HDF5 results file instead, alongside "final_energy", "final_energy_variance" and "energy_history". The result names that file in "results_file_name". - API reference: drop "states" and "eigenvector" from the result table, add "results_file_name", and point "energy_variance" at the states in the results file. - Guide: show the 4.0.0 result, list what the results file holds, and add examples that create a QiskitServerless client, download the file and read it with h5py. Add a Changelog section that starts at 4.0.0. - Tutorial: install h5py, and download and read the results file for each calculation. Co-authored-by: Shane McFarthing <shane.mcfarthing@gmail.com> Co-authored-by: Rowan Pellow-Jarman <rowanpellow@gmail.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The guide downloaded the results file with serverless.file_download(results_file_name, function) and then opened results_file_name. That fails with FileNotFoundError: without target_name, qiskit-serverless saves the file as downloaded_<8 hex>_<name> (qiskit_serverless/core/files.py, 0.36.0). The comment above the call, "saved ... under the same name", was wrong for the same reason. Pass target_name=results_file_name so the file lands under the name the next line opens, and make the comment say what the call does. The tutorial still asks for the path by hand and is left alone for now. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The licensed-use example passed backend_name="ibm_torino". Current qiskit-ibm-catalog checks backend access before it submits a job, so on an instance without ibm_torino the example stops with "Backend 'ibm_torino' is not available or you do not have access to it". It now passes backend_name, as the rest of the guide does, with a comment giving the 14 qubits that H2O in STO-3G needs (7 orbitals). The example also built its catalog from token and instance placeholders, unlike "Get started", which uses the saved account. It now does the same: QiskitFunctionsCatalog(channel="ibm_quantum_platform"). Checked against production 4.0.0 from a test instance. With a placeholder licence token, the job reaches the function and is refused with TokenNotFoundError (1201), as expected. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The guide, tutorial and API reference described the 4.0.0 function. None of them mentioned function_size, estimate_only or resource_usage, and the guide told every reader that runs were limited to 20 qubits unless they held a license. Under 5.0.x, someone without a token has no qubit limit: they pick a function size and are billed per run. - API reference: document function_size (sizes, fees, and the fail-fast check), estimate_only and its response, and the function_version and metadata.resource_usage keys in the result. - Guide: add "Limits and billing", covering sizes, estimating before running, and resource usage, ahead of a "Licensed use" section. Pass function_size in the examples, and list the error codes the function returns. - Tutorial: submit at the size each part needs instead of describing FeP-NO as needing a license. Give each part its own variable names, so re-running cells out of order cannot mix Li2S and FeP-NO data. This is fork PR #3, moved onto hivqe-4.0.0 as one commit so that it reaches IBM as its own change after 4.0.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Renaming it to casci_result_fepno took the line past 88 characters, so ruff format --check, run by IBM's lint (tox -e lint), would fail. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.0.0 is what changes for a user who has no licence token. They are no longer capped at 20 qubits. Instead they choose a function_size and are billed per run at it, and a size too small for the problem is rejected with 1221 before any QPU time is spent. The entry also covers estimate_only, the function_version and metadata.resource_usage keys, and the error codes. Checked against the qiskit-functions-hivqe-v5.0.2 tag in QunovaPulsar: the size table and the default "m" (function_size.py), FunctionSizeTooSmall raising 1221 (errors.py), and the result keys (runner.py). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Performance section's Li2S loop passed no function_size, so under
5.0.x it runs at the default "m", which allows 20 qubits. Li2S in
STO-3G with no active space needs 38. A reader without a licence token
would get error 1221 on the first geometry, before any QPU time was
spent. It now passes function_size="l".
Sized with the function's own problem_size.estimate_problem_size at
qiskit-functions-hivqe-v5.0.2, with its default options. That check
gives NH3 16 qubits ("m", as the guide passes), H2O 14 (licensed, so
not size-checked), and Li2S 38 ("l"). The tutorial's runs already pass
the sizes they need: Li2S 20 qubits at "m", FeP-NO 44 at "l".
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
estimate_only runs inside the function, so the platform treats it as an execution: the job starts a container at the submitted size (it ran on general_m in a test on -dev) and, under usage-based billing, owes that size's licence fee. IBM's gateway emits the fee for any Fleets job that reaches RUNNING (qiskit-serverless gateway/core/services/job_transitions.py, specs/OUTBOX.md). It also took about two minutes, of which 0.003 s was the sizing. IBM's launch item 4 asked for an estimator users run before submitting, not an execution. The qubit count follows a simple rule that PySCF can apply on the reader's machine: 2 x AVAS's active space when avas_aolabels is set, else 2 x len(active_orbitals), else 2 x the basis size. The guide now gives that rule and a short function. On 11 cases it matches the function's own problem_size.estimate_problem_size at qiskit-functions-hivqe-v5.0.2, including AVAS at the default and zero thresholds and AVAS together with an active list. - Guide: replace the estimate_only cell and its result table with the rule and the function (NH3 gives 16 qubits, so "m"). Say that a run rejected for being too small is still billed at the size chosen; the 5.0.0 EULA (5.4.4) says the same. - API reference: drop estimate_only and its output section, add the billing note to function_size, and link to the guide's section. - Changelog: point to the local check instead of estimate_only. The function still accepts estimate_only; it is just no longer the documented way to size a run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The function passed only basis, charge and unit to gto.M, and the text asked readers to add any other option themselves. Options such as cart change the basis size, so a reader who missed that got the wrong count: H2O in 6-31G* with cart=True is 38 qubits, not 36. The function now passes the same molecule options the function does (basis, charge, unit, symmetry, symmetry_subgroup, nucmod, pseudo, cart, magmom) and defaults the basis to sto-3g, as the function does. The text says to install PySCF with pip. Compared on 15 cases against the function's own sizing at qiskit-functions-hivqe-v5.0.2, now including cart, Bohr units and a charged molecule. All match. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Earlier commits on this branch replaced estimate_only with a PySCF function, hivqe_num_qubits(), that readers could run on their own machine. That put our sizing implementation in the public guide. Other partners document the rule and offer an in-function estimate: Qedma's guide gives its QPU-time formula and an estimate_time_only run. The guide now follows that pattern: - The qubit rule is a table: 2 x the orbitals AVAS selects, else 2 x len(active_orbitals), else 2 x the basis size. The NH3 example is worked through (8 orbitals, 16 qubits, "m"). - estimate_only=True is back, with the call, its output (taken from a real -dev run) and its fields. The text says it is billed as a run at the size it is submitted at, is never rejected for being too small, and so should go at "s". The call passes function_size="s". - The API reference gets estimate_only and its output section back, with the same billing note. The Changelog entry says the same. Kept from the earlier commits: rejected runs are billed at the size chosen, and the Li2S example passes function_size="l". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Arguments are now checked against the function's argument schema when run() is called, so describe validate_arguments() and arguments_schema in the guide and the API reference. Add a 5.0.3 changelog entry: orbital_coeffs works and takes a NumPy array, ansatz_entanglement accepts any case, avas_threshold takes a whole number, and the orbital lists must not repeat an entry. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
IBM asks every function for a size estimator that users can run before they
submit, and wants its code public. Put hivqe_chemistry_size_estimator.py,
the file IBM and the function size a job with, word for word under "Check
the size before you run", with a call on the guide's NH3 example ("m").
It needs only PySCF, submits nothing and costs nothing; estimate_only stays
as the in-function alternative, billed as a run. Add it to the 5.0.3
changelog.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
From 5.0.3 the function refuses any run submitted at a size too small for its problem, licensed and trial runs included, since the size is also the machine the job runs on. Say so under Limits and billing, Licensed use and the function_size reference, give the licensed example a function_size, and add it to the 5.0.3 changelog. estimate_only is gone from the function: the size estimator answers the same question on the reader's own machine, free. Remove its guide cells, its input and output sections in the API reference, and its 5.0.0 changelog line; 5.x has not been published, so no one has relied on it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The function-size rules were repeated in Limits and billing, Function sizes, Check the size and Licensed use; they are now in Function sizes only. The trial limit is a note under the table it qualifies. How run() refuses a bad argument, and validate_arguments(), move from the end of the error section to the Example, right after the first run(). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Its 124 lines sat between Function sizes and Licensed use. The definition and the NH3 call now form a section before the Changelog, so the notebook still runs top to bottom, and Check the size before you run keeps the table and a link. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
validate_arguments() came after the first run(), so "check without running" followed a run. It now comes first, and says the size is the estimator's job. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…example The reference gave magmom a default of 1_000 (it is None), gave avas_threshold a range of 0 to 2 that nothing checks, left out max_states' upper bound, and did not list use_session at all. The example now links to the full option lists. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On a narrow page the eight-column table wrapped "46547 s" between the number and the unit. A non-breaking space keeps them together. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The 5.0.3 entry sent readers to Fetch error messages for validate_arguments(), which now lives in the Example. Next steps listed the same tutorial twice. What happens at a wrong size is now one bullet per case, and the example's qubit count sits with the run it explains. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every IBM device has more qubits than these examples use, so the qubit counts never limit the choice; access does. The size each example needs stays in its function_size comment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A new reader could not tell who they were or what a run costs: the two ways to use the function were never named, "trial" appeared only in a note, and billing was spread over five places, with the size estimator near the end of the page. - Get started opens with a table of the two ways to use HI-VQE, usage-based and licensed: how to start, qubits, what you pay. - Function sizes and billing gathers sizes and fees, a table of what is billed, the qubit rule and the size estimator in one section. - The size fee is called the per-run fee, since "license fee" is also what a licensed customer pays Qunova. - The error example and the Li2S cell say that they are billed. - Headings use ## and ### only; Benchmarks moves under Performance. The API reference and tutorial links into the guide follow the new anchors. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Readers only need estimate_size, but the full estimator took up most of the billing section. The code cell is unchanged and still runs; it is now shown only when the reader opens it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The section listed every option that shapes the active space. Readers need the rule and an example; the size estimator handles the options. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Production goes from 4.0.0 straight to 5.0.x, so the entry lists what changed since 4.0.0. Fixes for problems only -dev ever had are dropped. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The tutorial said function_size was passed through and not checked on a license. Since 5.0.3 every run is checked, and the size sets the compute the run uses, which a licensed run pays for as classical compute time. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Only line breaks change: the code parses to the same tree as the function's hivqe_chemistry_size_estimator.py. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A rejected argument gets an exception describing what failed; for an unknown name it does not name the argument. - active_orbitals indexes the orbitals of the basis, not the qubits. - A licensed run is checked against its size and pays for the compute the size sets, but is not charged the per-execution fee. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Every run passed backend_name="", which the argument schema refuses. Setup now picks a backend with enough qubits for Part 2. - Part 1 freezes five orbitals, so its active space is (10o,12e), not (10o,10e) with six frozen; the CASCI reference matches (10o,12e). - 18.0 RU is the per-execution fees; QPU and compute time come on top. - Results files are downloaded under their own names, and the reading example opens one of them instead of a placeholder path. - Drop a stale output of the FeP-NO geometry cell, and the old qiskit-ibm-runtime pin. - Fix typos, and spell HI-VQE as the guide does, in the title too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The title is listed in docs/tutorials/index.mdx and _toc.json, which are not ours to change for a spelling. The body keeps HI-VQE. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Sizes follow qubits and max_states (5.0.7): the size tables, the size estimator (copied from the 5.0.8 function), and the examples' sizes and reasons. The Li2S benchmark now fits "m". - Licenses no longer use a token (5.0.7): the licensed-use section and the tutorial's licence note drop the wrapper and token, and the error table drops 1201, 2409 and 4630. 4500 now means a trial run above size "s". - A stopped job returns what it had computed (5.0.6): new "Results of a stopped job" section, and a note in the API reference's outputs. - Changelog entries for 5.0.6, 5.0.7 and 5.0.8, and the random seed in "Get support". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The size tables lose their fee column, and the Li2S benchmark and the tutorial no longer total the fees in resource units. The docs still say that a usage-based run pays a per-execution fee, higher for a larger size, and that a licensed run does not. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Collaborator
Author
|
@supalert-qunova This version is almost the same comparing to the previous version you reviewed. Removed the fee because the fee is the internal rate between IBM and Qunova. Also updated the estimation code with the new version. After the review, I will make the PR to the IBM. Planning on next week. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Important
Do not merge. This PR is the review copy of what we will send to IBM (Qiskit/documentation). Its base,
upstream-main, is a copy of IBM'smain(refreshed today), so Files changed shows exactly what IBM will receive. Once it is approved, this same branch goes to IBM as the upstream PR.Note
Files changed also contains the 4.0.0 changes. IBM has not merged our 4.0.0 PR (Qiskit/documentation#5758) yet, and this branch is built on it. Those changes were reviewed in #6. The screenshots below compare against 4.0.0 (
hivqe-4.0.0), so they show only what 5.0.x adds.What changes for users in 5.0.x (up to 5.0.8)
From the guide's Changelog.
5.0.8
RUNNING: OPTIMIZING_FOR_HARDWAREand never reached the QPU.5.0.7
max_statesas well as its qubits:"s"up to 20 qubits andmax_statesof 1,000,"m"up to 48 qubits and 10,000,000,"l"above either.tokenargument is ignored, with a note in the job log. Error codes 1201, 2409 and 4630 are no longer returned."s", and are rejected with error code 4500 above it.5.0.6
job.cancel()) returns what the run had computed before it was stopped, with"status": "canceled".5.0.4
function_sizeargument:"s","m"(the default) or"l". Runs with a license token are checked against the function size too.run(), and a malformed call is refused before a job is created, at no charge. Check them in advance withvalidate_arguments()."function_version"and"metadata", whose"resource_usage"gives the time spent in each stage of the job, including QPU time.Three pages change: the guide, the API reference and the tutorial. Nothing else.
Before and after
Screenshots come from the local docs preview (
./start), which uses the same renderer as the IBM docs site. Before is the 4.0.0 docs; after is this branch at 5.0.8.Guide: Get started
Opens with the two ways to use HI-VQE, usage-based and licensed: how to start, how you get access, what you pay.
Guide: Example
Steps get their own headings. New: checking the arguments with
validate_arguments(), choosingfunction_size, and running from an FCIDUMP file. The licensed example's backend comment no longer names a qubit count.Guide: Results of a stopped job (new)
What
job.result()returns for a job stopped withjob.cancel().Guide: Function sizes and billing (new)
Sizes, a table of what is billed, the size a problem needs, and the size estimator (its code folds away). Fee amounts are left out; the page says only that a larger size has a higher per-execution fee.
Guide: Licensed use
How to request a license. No license token is needed; one still passed is ignored.
Guide: Fetch error messages
The error codes the function returns, with what each means. The example run is marked as billed.
Guide: Changelog
API reference: Inputs
Arguments are checked before a job is created. New
fcidump_file_nameargument.API reference:
use_sessionandfunction_size(new)The
function_sizetable gives qubits andmax_statesfor each size, without fee amounts.API reference: Outputs
Adds
"function_version"and"metadata", and a note on what a stopped job returns.Tutorial: setup
Picks a backend instead of passing
backend_name="", which the function now refuses. Says what each part costs, with a license and with trial access.Tutorial: Part 1 options
The Li2S active space is (10o,12e), with five frozen orbitals, as the code and the CASCI reference have it.
Tutorial: Part 1 runs (new)
The runs give their
max_states, which together with 20 qubits puts them at"m".Tutorial: Part 2 (new)
Part 2 runs at
"l"because of itsmax_states. No license token, and no qubit limit on a license.Tutorial: results files
Files are downloaded under their own names, and the reading example opens one of them.
How the code was checked
validate_arguments()onqunova/hivqe-chemistry-dev. The tutorial's oldbackend_name=""is refused withminLength.hivqe_chemistry_size_estimator.py; only line breaks differ, for ruff. Run locally with PySCF, it gives the sizes the examples use: NH3 withmax_states=2000"m", the NH3 FCIDUMP"m", and NH3 withmax_states=1000"s".Known and left as they are
Fee amounts: the per-execution fee per size is left out of all three pages until IBM confirms whether it should be published.
Guide, Li2S PES plot: the plot is CASCI(12o,12e), 24 qubits; the code under it runs the full STO-3G basis, 38 qubits. Left as it has been since the page was published.
Guide, Benchmarks table: lists Li2S as (10o,10e). The tutorial's identical setup is (10o,12e); unverified, so unchanged.
Tutorial title keeps "HiVQE", as the shared tutorial index and toc list it; the body uses HI-VQE.
Send to IBM
After approval, and after IBM merges Qiskit#5758:
https://github.com/Qiskit/documentation/compare/main...QuNovaComputing:qiskit-documentation:hivqe-5.0.x?expand=1
🤖 Generated with Claude Code