Skip to content

examples: correct the bitstring layout in the README and drop stale docs - #14

Merged
hfwen0502 merged 1 commit into
mainfrom
fix-examples-readme
Sep 1, 2026
Merged

examples: correct the bitstring layout in the README and drop stale docs#14
hfwen0502 merged 1 commit into
mainfrom
fix-examples-readme

Conversation

@hfwen0502

Copy link
Copy Markdown
Collaborator

The bitstring layout was documented backwards

python/examples/README.md said:

Each bitstring has length 2 × NORB — the first NORB bits are alpha (spin-up)
orbitals and the last NORB are beta (spin-down)

qiskit-addon-sqd does the opposite. _prepare_ci_strings() reads

samples_a = ... bitstring_matrix_to_integers(samples[:, config.norb :])   # RIGHT half -> alpha
samples_b = ... bitstring_matrix_to_integers(samples[:, : config.norb])   # LEFT  half -> beta

so the layout is [beta | alpha]. Anyone constructing a count_dict.json from that
sentence 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 so
read 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

  • --samples is no longer uniform random; it draws at the target Hamming weights. The text
    now states plainly that random determinants give a random subspace, so the energy is not
    meaningful, and points to --counts for real results.
  • The notebook section still described "uniform-random bitstrings + 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 the README and in
    the run_sqd_sbd.py 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. The matching "fork" reference is gone too.
  • The lead run_sqd_sbd.py example — in both the README and the docstring — now passes
    --counts count_dict_h2o.json instead of relying on random samples, and the file itself
    is documented (275 bitstrings from the vendored h2o-1em3-alpha.txt, 75,625-determinant
    subspace).
  • 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 of this project.

Verification

Docs-only, so nothing to execute. Checked rather than eyeballed:

  • Every --flag in run_sqd_sbd.py and run_sbd_diag.py diffed against the README; the
    ones not listed are all covered by its "run --help for the full list" pointer.
  • The layout claim confirmed against installed qiskit-addon-sqd 0.13.1.
  • The SPMD claim confirmed by checking is_control_process and broadcast on the release.
  • Backend wording checked against python/__init__.py (all compiled backends load eagerly;
    the offload one cannot co-load with CPU/Thrust).
  • pytest --nbmake run_sqd_sbd.ipynb run from python/examples/ exactly as the README now
    documents: 1 passed.
  • -76.236 cross-checked against vendor/sbd-upstream/data/h2o/README.md, which publishes
    -76.23594663 for the 1.0e-3 / 275-bitstring row.

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.
@hfwen0502
hfwen0502 merged commit 9cbf579 into main Sep 1, 2026
6 checks passed
@hfwen0502
hfwen0502 deleted the fix-examples-readme branch September 1, 2026 20:01
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