examples: correct the bitstring layout in the README and drop stale docs - #14
Merged
Conversation
The count_dict.json format section in examples/README.md had the spin halves inverted. It said the first NORB bits are alpha and the last NORB are beta; qiskit-addon-sqd does the opposite -- _prepare_ci_strings() takes samples[:, norb:] as alpha and samples[:, :norb] as beta, i.e. the layout is [beta | alpha]. Anyone building a counts file from that sentence would have swapped their spin sectors. The error went unnoticed because all three example bitstrings were (5,5) symmetric and so read the same either way; the first is now the Hartree-Fock configuration, which is unambiguous. Also documents the within-half order (orbital 0 is the rightmost bit), which was missing entirely. Other corrections, all drift from recent merges: - --samples is no longer uniform random (it draws at the target Hamming weights), and the text now says plainly that the energy from random determinants is not meaningful. - The notebook section still described uniform-random bitstrings plus HF initial_occupancies and quoted ~-76.19 Ha. It now uses the bundled count_dict_h2o.json and reaches ~-76.236 Ha. - Dropped the instruction to install qiskit-addon-sqd from @main, in both the README and run_sqd_sbd.py's module docstring. The distributed (SPMD) support is in 0.13.1 -- is_control_process and broadcast are both present in the release -- which is what pyproject.toml already requires. Dropped the matching "fork" reference too. - The lead run_sqd_sbd.py example, in both the README and the docstring, now passes --counts count_dict_h2o.json rather than relying on random samples, and the file itself is documented. - Backend list gained gpu-omp, with a note that it links a different OpenMP runtime (libnvomp) and is normally its own install. "Both backends" -> all compiled backends, since there are three. - Notebook run command uses pytest --nbmake (what CI runs); nbconvert is not a declared dependency.
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.
The bitstring layout was documented backwards
python/examples/README.mdsaid:qiskit-addon-sqd does the opposite.
_prepare_ci_strings()readsso the layout is
[beta | alpha]. Anyone constructing acount_dict.jsonfrom thatsentence would have swapped their spin sectors — for an open-shell system
(
num_elec_a != num_elec_b) every bitstring would then fail postselection.The error survived because all three example bitstrings were
(5, 5)symmetric and soread identically either way. The first example is now the Hartree–Fock configuration, which
is unambiguous and doubles as the reference determinant. The section also documents the
within-half order — orbital 0 is the rightmost bit — which was missing entirely.
Other corrections, all drift from #12 and #13
--samplesis no longer uniform random; it draws at the target Hamming weights. The textnow states plainly that random determinants give a random subspace, so the energy is not
meaningful, and points to
--countsfor real results.initial_occupancies" and quoted ~-76.19 Ha. It now uses the bundledcount_dict_h2o.jsonand reaches ~-76.236 Ha.qiskit-addon-sqdfrom@main— in the README and inthe
run_sqd_sbd.pymodule docstring. The distributed (SPMD) support is in 0.13.1(
is_control_processandbroadcastare both present in the release), which is whatpyproject.tomlalready requires. The matching "fork" reference is gone too.run_sqd_sbd.pyexample — in both the README and the docstring — now passes--counts count_dict_h2o.jsoninstead of relying on random samples, and the file itselfis documented (275 bitstrings from the vendored
h2o-1em3-alpha.txt, 75,625-determinantsubspace).
gpu-omp, with a note that it links a different OpenMP runtime(
libnvomp) and is normally its own install. "Both backends" -> all compiled backends,since there are three.
pytest --nbmake(what CI runs);nbconvertis not a declareddependency of this project.
Verification
Docs-only, so nothing to execute. Checked rather than eyeballed:
--flaginrun_sqd_sbd.pyandrun_sbd_diag.pydiffed against the README; theones not listed are all covered by its "run
--helpfor the full list" pointer.qiskit-addon-sqd0.13.1.is_control_processandbroadcaston the release.python/__init__.py(all compiled backends load eagerly;the offload one cannot co-load with CPU/Thrust).
pytest --nbmake run_sqd_sbd.ipynbrun frompython/examples/exactly as the README nowdocuments:
1 passed.-76.236cross-checked againstvendor/sbd-upstream/data/h2o/README.md, which publishes-76.23594663for the 1.0e-3 / 275-bitstring row.