Document how to retrieve TPB amplitudes, and the bitstring packing order

[Jim Garrison (garrison)]

Two things a user currently has to discover by reading the vendored C++ or by experimenting. Both came up in a user question about the Python bindings.

TPB has two wavefunction output paths, and they write different formats

tpb_diag returns no amplitudes, and there are two ways to get them:

	sbd_data.dump_matrix_form_wf	savename argument
Writes	the full len(adet) × len(bdet) subspace, gathered onto one rank	one file per b_comm position, each holding only that rank's block
Path	exactly what you set	f"{savename}{rank_b:06d}.bin"
Header	none	three size_t (adet_range, bdet_range, det_length), then that block's determinant words
Payload	float64, row-major over α×β	adet_range × bdet_range float64
Intended for	analysis	checkpoint/restart, paired with loadname

dump_matrix_form_wf is what almost every caller wants, and is already what this package's own SQD integration uses — sbd_solver.py sets it and reads the result back with a bare np.fromfile. But it appeared only as a one-line pybind docstring and a CLI flag in examples/tpb/run_sbd_diag.py; it was absent from the README's TPB section and from the tpb_diag docstring, both of which mention savename alone. Following the function signature therefore led to the per-rank restart layout, which is the wrong thing to parse for analysis.

This adds the comparison to the README, a Note: block on tpb_diag, a pointer on tpb_diag_from_files, a row in the TPB_SBD config table, and a fuller pybind docstring. It also records that the .dat/.txt text form is written with the stream's default formatting, so it carries roughly 6 significant digits rather than full float64 — restart.h sets precision(16) on std::cout, not on the file stream.

The word-packing convention was unstated

Bitstrings are packed from the right: the trailing bit_length characters become word 0, so the leading characters of a string longer than one word land in the last word rather than the first.

from_strings(["0011"], 20, 4)           # -> array([[3]], dtype=uint64)
from_strings(["1" + "0" * 69], 63, 70)  # -> array([[ 0, 64]], ...)
from_strings(["0" * 69 + "1"], 63, 70)  # -> array([[1, 0]], ...)

Worth stating explicitly because getting it backwards produces a valid-looking but wrong subspace rather than an error. It is documented on from_strings, which #53 lists in the API reference, rather than on the singular from_string, which it deliberately leaves out; the singular forms point at it.

Documentation only — no behavior change, hence an other release note.

GDB needed no changes: #46 already documents its amplitude retrieval and per-shard file layout in examples/gdb/README.md.

Merged main after #53

#53 landed first and changed where this documentation belongs, so the merge commit is followed by a commit reconciling the two. No files overlapped — #53 is docs/apidocs/*.rst only — but three things needed fixing:

• The packing convention was written on from_string, which docs: list the API users call, and document the configuration fields #53's curated autodoc list omits, so it would never have rendered. It moves to from_strings, which had no packing documentation of its own despite being the form users are steered to.
• dump_matrix_form_wf is now in docs: list the API users call, and document the configuration fields #53's TPB_SBD field table, so the README row defers to the format section rather than describing the field twice.
• A claim about sbd_solver.py was stale against Let SBD choose the SQD carryover (qiskit-addon-sqd#369) #49: the wavefunction write is skipped when SBD selects the carryover itself (carryover_type 1, against an addon that accepts it), since the next subspace then arrives in carryover_adet/carryover_bdet. Saying it "uses" the dump implied the write always happens.

tox -e docs passes with no warnings.

---

This pull request was drafted by Claude Opus 5 under my guidance.

[Jim Garrison (garrison)]

Mergify (@Mergifyio) backport stable/1.7

[mergify]

backport stable/1.7

⚠️ Cannot use the command backport stable/1.7

Details

⚠ The product Workflow Automation needs to be activated to enable this feature.

[mergify]

backport stable/1.7

✅ Backports have been created

Details

• #57 Document how to retrieve TPB amplitudes, and the bitstring packing order (backport #55) has been created for branch stable/1.7