Repository navigation
Add release notes for everything since 1.6.1 - #45
Jim Garrison (garrison) wants to merge 6 commits into
Conversation
The project had no documentation build at all: no `docs/`, no reno, and no docs CI. Everything user-facing lived in the README, whose hand-written "API Reference" section duplicated the module structure by hand and was free to drift from the code. This adds the smallest thing that is actually real: an API reference generated from the existing docstrings, a working reno setup, and a CI job that fails a pull request when either breaks. Guides and notebooks are deliberately out of scope and can be layered on later without redoing any of this. Two properties of this package shaped the setup. First, autodoc needs the package genuinely installed rather than merely on `sys.path`: the import name `sbd` does not match its directory `python/`, and only setuptools knows the `package-dir` mapping, so the docs environment builds and installs the wheel like the test environments do. Second, importing `sbd` is cheap and GPU-free because backends load lazily, so a CPU-only build on a GPU-less runner is enough to document it. Two details differ from the equivalent setup in qiskit-addon-sqd, where a verbatim copy would have been wrong here: - `linkcode_resolve` needs two separate spellings, since the installed directory (`sbd/`) and the in-repository directory (`python/`) differ. Using one token for both would 404 on every "source" link. - The `sbd` page excludes the `sbd_solver` member. It appears in `sbd.__all__` as a submodule while also having a page of its own, which is a duplicate object description and therefore fatal under `-W`. Enabling `-W` surfaced two pre-existing docstring defects, both fixed here: an unmarked indented block in `assemble_rdms` is now a literal block, which also renders the index formulas as intended, and the over-indented alias list in `init` is reflowed to the indentation napoleon expects. Note that reno only sees notes that git tracks, so a newly added note must be staged before it renders. The release-notes page is also cached across incremental builds; `tox -e docs-clean` forces it to be regenerated. Assisted-by: Claude Opus 5
PR #43 adds the reno machinery but deliberately ships no notes, so the release-notes page renders empty. Twenty-eight commits have landed since the 1.6.1 tag, several of which change behavior a user has to know about, and none of it is written down anywhere a user will look. Backfill that history as 19 notes: 6 upgrade, 7 features, 6 fixes. The 1.6.1 tag is far behind main, so every commit covered here is unreleased and the notes render under "Upcoming release" until 1.7.0 is tagged; they need no coordination with the version bump in #42. The upgrade notes are the point of the exercise. Multi-iteration SQD results move, because the amplitudes handed back to the SQD loop were being replaced by a uniform array and are now correct. h_comm_size is gone from the config objects, which raises AttributeError on assignment and, less obviously, is silently ignored as an sbd_config key. carryover_type now defaults to 0, SBD_BUILD_BACKEND=both is rejected in favor of all, backends load one per process with OMP_TARGET_OFFLOAD defaulted to MANDATORY, and pybind11 is no longer a runtime dependency. Examples get one combined note rather than one per pull request: they are scripts in the repository, not importable API, so the note records the parameter regrouping, the dropped Hartree-Fock seed and the new enlarge-subspace driver without itemizing seven pull requests. CI and documentation-only changes get no notes. Three further changes are deliberately omitted as invisible to a 1.6.1 user: the importlib.metadata version switch, the vendored upstream bump (the makestring template instantiation preserves the exposed signature), and the internal GPU build-flag cleanups. Assisted-by: Claude Opus 5
Jim Garrison (garrison)
added
the
documentation
Three commits landed on main after the branch point, two of which changed behavior since 1.6.1 and so need notes of their own. #48 bound tpb::SBD::seed. init was already exposed and init == 1 means a random start vector, but seed was not bound, so every random-start TPB run began from upstream's default with no way to vary it -- which defeats the point of a random start. GDB_SBD has bound seed since before 1.6.1, so this was an asymmetry between the two config structs. Filed as a feature: a new public config attribute. #44 moved the examples from python/examples to examples/tpb. At the 1.6.1 tag MANIFEST.in shipped them under the old path, so anyone holding a reference to it -- a checkout, an unpacked sdist -- needs to update. The note says plainly that they were never importable from the installed package in either layout, since packages/package-dir did not change; the relocation is about the source tree and the sdist. It also covers the INSTALL.md split out of README.md. The same PR taught setup.py to read NVHPC_ROOT, and to probe compilers/bin as well as bin. NVIDIA's modulefile sets NVHPC_ROOT to the version root, one level above the compiler, so the value NVIDIA hands out matched neither of the things 1.6.1 looked for. Filed as a fix rather than a feature: where it also left nvc++ off PATH, the GPU backends were skipped and gpu_omp_offload failed claiming NVHPC was missing on a host where it was installed. Finally, examples-reworked said the drivers ship under python/examples, which #44 made wrong; it now reads examples/tpb. Assisted-by: Claude Opus 5
|
Pushed a610a71, covering three commits that landed on #48 — #44 — examples moved from #44 — Correction: 22 notes total. One trap worth recording for anyone building these docs locally: an uncommitted edit to an existing note makes reno's sphinxext emit the "Upcoming release" sections twice, which under This comment was generated by Claude Opus 5 under my guidance. |
…f.yaml Co-authored-by: Sophia Wen <hfwen@us.ibm.com>
This branch has not been deployed
2 participants
#43 adds the reno machinery but deliberately ships no notes, so the release-notes page it builds renders empty. Twenty-eight commits have landed since the 1.6.1 tag, several of which change behavior a user has to know about, and none of it is written down anywhere a user will look. This backfills that history as
1922 notes:67 upgrade,78 features,67 fixes.The 1.6.1 tag is far behind
main, so every commit covered here is unreleased. The notes render under "Upcoming release" until 1.7.0 is tagged, at which point reno attaches them to it — so this needs no coordination with the version bump in #42, and the notes are filed loose inreleasenotes/notes/rather than in a1.7.0/subdirectory.The upgrade notes are the point of the exercise
h_comm_sizeis gone fromTPB_SBD/GDB_SBD(Separate SQD parameters from SBD parameters, and expose the ones that were unreachable #28). Assignment now raisesAttributeError, and — less obviously, so the note says it explicitly — an"h_comm_size"key insbd_configis now silently ignored.carryover_typedefaults to 0 (Separate SQD parameters from SBD parameters, and expose the ones that were unreachable #28): a speedup, with bit-identical energies.SBD_BUILD_BACKEND=bothis rejected in favor ofall(Conda-friendly builds, AMD GPU support, and macOS OpenMP #23).OMP_TARGET_OFFLOADdefaulted toMANDATORY(Conda-friendly builds, AMD GPU support, and macOS OpenMP #23) so a silent host fallback becomes an error.pybind11is no longer a runtime dependency (Drop pybind11 from the runtime dependencies #33).Scope
Examples get one combined note rather than one per pull request: they are scripts in the repository, not importable API. It records the parameter regrouping, the dropped Hartree-Fock seed and the new enlarge-subspace driver without itemizing seven pull requests. CI and documentation-only changes get no notes.
Three changes are deliberately omitted as invisible to a 1.6.1 user: the
importlib.metadataversion switch (#16), the vendored upstream bump (#24 — themakestringtemplate instantiation preserves the exposed signature), and the internal GPU build-flag cleanups (#17, #25).Verification
sphinx-build -W --keep-going, the same commandtox -e docsruns, succeeds with zero warnings. All1922 notes render under the correct New Features / Upgrade Notes / Bug Fixes headings, and all 22:func:cross-references resolve to real anchors — 22 roles, 22 links, so none failed silently.reno lintpasses.This pull request was generated by Claude Opus 5 under my guidance.