Execute the example notebook in CI (#7)

* Execute the example notebook in CI

python/examples/run_sqd_sbd.ipynb drives this package from qiskit-addon-sqd's
configuration recovery loop, which nothing else in the suite covers: the reference
energy tests call tpb_diag_from_files directly. Running the notebook checks that the
example still works against the current code, and that the integration it documents
has not drifted.

Follows the extras layout in qiskit-addon-utils: a `basetest` extra holds what every
test environment needs, `nbtest` adds the harness, and `notebook-dependencies` names
what the notebooks themselves import. The last two are separate because pyscf and
qiskit-addon-sqd are needed only to run the examples, not to use sbd.

The tox environment is factored as py{...}-notebook so a specific interpreter can be
selected, matching the sibling repos. CI runs `tox -e py,notebook,mpi` in one
invocation, which keeps the extension compiled once and installed into all three:
verified from a clean .tox as one build_wheel and three install_package, 70 seconds
for the set.

Note that qiskit-addon-sqd is bounded at 0.13.1 rather than 0.13, since the 0.13.0
that a minimum-version pin would resolve to was never released.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Apply suggestion from @garrison

* Spell out the notebook environment names

The section name I wrote, {,py-,py3-,py310-,...}notebook, does not define the
environments it appears to. tox expands numeric ranges in a section name before
splitting it on braces, so `py314-` parses as `py3` plus the open-ended range `14-`.
The name expanded to 18 environments, 15 of them junk -- py3notebook, 4notebook
through 14notebook, pynotebook -- and none of them py310-notebook through
py314-notebook.

Those five were still in envlist, so `tox` created them from the generic [testenv]:
`tox config -e py312-notebook` reported `commands = pytest`, meaning a bare `tox` ran
the unit suite five extra times and never executed a notebook. Only the explicit
`tox -e notebook` did, which is why CI passed.

Fixed by spelling the names out with the hyphen outside the braces, as in
Qiskit/qiskit-addon-utils#214, which found and explained this. `tox l` now lists no
junk, and all of notebook, py310-notebook through py314-notebook resolve to the nbmake
command; py312-notebook runs the notebook in 22 s.

The py- and py3- variants are dropped, since they resolved to the same interpreter as
the bare notebook environment and added nothing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: garrison

.github/workflows/test_latest_versions.yml

@@ -46,11 +46,11 @@ jobs:
           pip install tox
       - name: Test using tox environments
         shell: bash
-        # One invocation rather than two, so that the extension is compiled once and
-        # the resulting wheel is installed into both environments. Running `tox -e py`
-        # and `tox -e mpi` as separate commands would compile it twice.
+        # One invocation rather than several, so that the extension is compiled once and
+        # the resulting wheel is installed into each environment. Running them as
+        # separate commands would compile it once per environment.
         #
-        # Not --parallel: the two environments would then race to install the same
-        # wheel, and the MPI tests want the runner's cores to themselves.
+        # Not --parallel: the environments would then race to install the same wheel,
+        # and the MPI tests want the runner's cores to themselves.
         run: |
-          tox -e py,mpi
+          tox -e py,notebook,mpi

pyproject.toml

@@ -31,10 +31,21 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-test = [
+basetest = [
     "pytest>=8.0",
+]
+test = [
+    "sbd-eigensolver[basetest]",
     "pytest-mpi>=0.6",
 ]
+nbtest = [
+    "sbd-eigensolver[basetest]",
+    "nbmake>=1.5.0",
+]
+notebook-dependencies = [
+    "qiskit-addon-sqd>=0.13.1",
+    "pyscf>=2.9",
+]
 
 [project.urls]
 Homepage = "https://github.com/Qiskit/sbd-eigensolver-python"

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 minversion = 4.4.3
-envlist = py{310,311,312,313,314}, mpi
+envlist = py{310,311,312,313,314}{,-notebook}, mpi
 isolated_build = True
 
 [testenv]
@@ -52,6 +52,22 @@ setenv =
 commands =
     mpirun -n {env:SBD_TEST_NPROCS} pytest --only-mpi {posargs}
 
+# Spelled out with the hyphen outside the braces. Writing this as
+# {,py310-,py311-,...}notebook does not work: tox expands numeric ranges in a section
+# name before splitting it on braces, so `py314-` parses as `py3` plus the range `14-`,
+# which produces junk environment names and never defines py310-notebook and friends --
+# those then silently fall through to [testenv] and run the unit tests instead. Nesting
+# braces is not an alternative either; it crashes tox outright.
+[testenv:{notebook,py310-notebook,py311-notebook,py312-notebook,py313-notebook,py314-notebook}]
+# nbmake runs each notebook with its own directory as the working directory, so the
+# relative paths the examples use to reach the vendored data resolve as they would for
+# someone running the notebook by hand.
+extras =
+    nbtest
+    notebook-dependencies
+commands =
+    pytest --nbmake --nbmake-timeout=3000 {posargs} python/examples/
+
 [testenv:slow]
 # The reference cases grow by roughly an order of magnitude in determinant count per
 # row of the upstream tables, and compute time scales worse than linearly in that, so