Skip to content

[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
upstream-mainfrom
hivqe-5.0.x
Open

seihyun-jeong wants to merge 41 commits into
upstream-mainfrom
hivqe-5.0.x

Conversation

@seihyun-jeong

@seihyun-jeong seihyun-jeong commented Oct 15, 2026 •

Copy link
Copy Markdown
Collaborator

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's main (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

  • Fixed runs of more than a few qubits that, in 5.0.6 and 5.0.7, stopped at RUNNING: OPTIMIZING_FOR_HARDWARE and never reached the QPU.

5.0.7

  • The function size a problem needs depends on its max_states as well as its qubits: "s" up to 20 qubits and max_states of 1,000, "m" up to 48 qubits and 10,000,000, "l" above either.
  • Licenses no longer use a license token. IBM enables the function on a licensed account for the term of the license. A token argument is ignored, with a note in the job log. Error codes 1201, 2409 and 4630 are no longer returned.
  • Runs with trial access are limited to function size "s", and are rejected with error code 4500 above it.
  • The job log gives the random seed of the run.

5.0.6

  • A stopped job (job.cancel()) returns what the run had computed before it was stopped, with "status": "canceled".

5.0.4

  • Runs execute on dedicated compute, sized by the function size you choose.
  • Runs without a license token are no longer limited to 20 qubits. Each run is billed per execution at the function size you choose with the new function_size argument: "s", "m" (the default) or "l". Runs with a license token are checked against the function size too.
  • Runs can take the problem from an FCIDUMP file you upload, in place of a geometry.
  • Added a size estimator that gives the function size a problem needs, on your own machine and at no charge.
  • Arguments are checked against the function's argument schema when you call run(), and a malformed call is refused before a job is created, at no charge. Check them in advance with validate_arguments().
  • Every error carries an error code, a message saying what went wrong, and what to do about it.
  • The result includes "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.

Before After

Guide: Example

Steps get their own headings. New: checking the arguments with validate_arguments(), choosing function_size, and running from an FCIDUMP file. The licensed example's backend comment no longer names a qubit count.

Before After

Guide: Results of a stopped job (new)

What job.result() returns for a job stopped with job.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.

Before After

Guide: Fetch error messages

The error codes the function returns, with what each means. The example run is marked as billed.

Before After

Guide: Changelog

Before After

API reference: Inputs

Arguments are checked before a job is created. New fcidump_file_name argument.

Before After

API reference: use_session and function_size (new)

The function_size table gives qubits and max_states for each size, without fee amounts.

API reference: Outputs

Adds "function_version" and "metadata", and a note on what a stopped job returns.

Before After

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.

Before After

Tutorial: Part 1 options

The Li2S active space is (10o,12e), with five frozen orbitals, as the code and the CASCI reference have it.

Before After

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 its max_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.

Before After

How the code was checked

  • The guide's and the tutorial's arguments pass validate_arguments() on qunova/hivqe-chemistry-dev. The tutorial's old backend_name="" is refused with minLength.
  • The size estimator cell is the 5.0.8 hivqe_chemistry_size_estimator.py; only line breaks differ, for ruff. Run locally with PySCF, it gives the sizes the examples use: NH3 with max_states=2000 "m", the NH3 FCIDUMP "m", and NH3 with max_states=1000 "s".
  • No paid run was made for this PR. Notebook outputs are unchanged, except a stale output removed from the tutorial's FeP-NO geometry cell.
  • The Lint checks in QUNOVA.md pass, and the pages render.

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

seihyun-jeong and others added 30 commits October 7, 2026 10:54
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>
seihyun-jeong and others added 8 commits October 15, 2026 12:00
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>
seihyun-jeong and others added 3 commits October 16, 2026 15:13
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>
@seihyun-jeong seihyun-jeong changed the title [Review before IBM] HI-VQE docs for 5.0.4 [Review before IBM] HI-VQE docs for 5.0.x (up to 5.0.8) Oct 23, 2026
@seihyun-jeong seihyun-jeong self-assigned this Oct 23, 2026
@seihyun-jeong

Copy link
Copy Markdown
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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant