Feature/issue 1274 notebook format check by rosspeili · Pull Request #1299 · quantumlib/OpenFermion

rosspeili · 2026-05-06T09:39:54Z

Adds check/nbformat so tracked Jupyter notebooks are checked with tensorflow_docs.tools.nbfmt (Cirq-style), wired into check/all, shell check, and CI.

Also adds tensorflow-docs to the pytest/dev lockfiles, rebases on current main, and runs nbfmt on all 15 .ipynb files so CI passes (most of the new diff is notebook formats).

Earlier version used the wrong module (nbformat) which was fixed to nbfmt with --apply for local fixes.

gemini-code-assist

Code Review

This pull request introduces a new script, check/nbformat, to validate and fix Jupyter notebook formatting using tensorflow_docs.tools.nbformat, and updates the project's dependency requirements and lockfiles. The review highlights two critical issues: the inefficiency of invoking the format checker in a loop rather than passing all files at once, and the breaking of environment compatibility for older Python versions caused by regenerating lockfiles with Python 3.13 instead of the project's minimum supported version.

rosspeili · 2026-05-17T12:15:26Z

Hey @mhucka any feedback on this also? No stress, just checking in. Thanks.

mhucka · 2026-05-30T04:19:38Z

@rosspeili Thank you for the contribution, and sorry for the long delay in getting back to this.

The merge conflicts are because files in the repo changed in the meantime, which is my fault for not reviewing this sooner, so I will take the time to fix it in a moment and push an updated version to your branch. (I hope you don't mind – it will save everyone time.)

A bigger problem is that this does not work. How did you test this? This is what happens when I run check/nbformat:

./check/nbformat
Found 15 notebook(s).
Running notebook format checker...
  Checking: docs/fqe/guide/introduction.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/fqe/tutorials/diagonal_coulomb_evolution.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/fqe/tutorials/fermi_hubbard.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/fqe/tutorials/fqe_vs_openfermion_quadratic_hamiltonians.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/fqe/tutorials/hamiltonian_time_evolution_and_expectation_estimation.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/binary_code_transforms.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/bosonic_operators.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/circuits_1_basis_change.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/circuits_2_diagonal_coulomb_trotter.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/circuits_3_arbitrary_basis_trotter.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/intro_to_openfermion.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/intro_workshop_exercises.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/jordan_wigner_and_bravyi_kitaev_transforms.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: src/openfermion/resource_estimates/pbc/notebooks/isdf.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: src/openfermion/resource_estimates/pbc/notebooks/resource_estimates.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat

mhucka · 2026-05-30T04:49:19Z

+declare -a errors=()
+for notebook in "${notebooks[@]}"; do
+    echo "  Checking: ${notebook}"
+    if ! python -m tensorflow_docs.tools.nbformat "${tf_args[@]}" "${notebook}"; then


tensorflow_docs.tools does not have an nbformat.

This could not have worked. How was this tested, exactly?

rosspeili · 2026-05-30T06:10:29Z

Hey @mhucka no stress at all. Appreciate the review and comments as always. As disclosed also in previews PRs, the PR description indeed is formatted with AI, based on a dump, but will make it more concise or just drop the original blurp. Code is hand written and passed through AI for review before pr. I used existing tests with py 3.13, but will check again and come back to you asap.

Please do feel free to push to my branch if available. Or suggest and I'll approve. 🙏

Add check/nbformat, a new bash script that checks the format of all tracked Jupyter notebook (.ipynb) files using the TensorFlow Docs notebook format checker (tensorflow_docs.tools.nbformat). The script: - Discovers all .ipynb files tracked by git via git ls-files - Runs python -m tensorflow_docs.tools.nbformat on each notebook - Defaults to check-only mode (non-destructive) - Accepts --fix to reformat notebooks in place - Accepts --help to print usage information - Exits non-zero if any notebook fails the format check Wire check/nbformat into: - check/all: called unconditionally alongside check/mypy and check/shellcheck, since notebook format is structural and not related to which Python files changed - check/shellcheck: added to the required_shell_scripts list (in sorted order) so shellcheck verifies the new script is present Add tensorflow-docs to dev_tools/requirements/deps/pytest.txt alongside the existing nbformat dep, since both are needed for notebook-related checks and belong in the same env grouping. Add a notebook-checks CI job to .github/workflows/ci.yaml that triggers when .ipynb files change and runs check/nbformat using the pytest.env.txt environment (which includes tensorflow-docs). Also add the new job to report-results so it is a required check.

Co-authored-by: Michael Hucka <mhucka@google.com>

…1274) The checker called a non-existent tensorflow_docs.tools.nbformat module. Align with Cirq by using nbfmt, regenerate lockfiles on current main, and format all tracked notebooks so CI can pass.

review-notebook-app · 2026-05-30T10:02:16Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

rosspeili · 2026-05-30T10:07:46Z

@mhucka thanks again for the patience and tips.

Rebased onto current main and fixed check/nbformat, I had the wrong module (nbformat vs nbfmt, per Cirq). Ran nbfmt locally on py3.13 and formatted the notebooks and lockfiles regenerated on top of main.

Let me know if I am missing anything. <3

gemini-code-assist Bot reviewed May 6, 2026

View reviewed changes

Comment thread check/nbformat Outdated

Comment thread dev_tools/requirements/envs/dev.env.txt

mhucka added area/devops Involves build systems, Make files, Bazel files, continuous integration, and or other DevOps topics area/docs Involves documentation, notebooks, README files, and similar area/tests Involves testing and test cases labels May 30, 2026

mhucka self-assigned this May 30, 2026

mhucka requested changes May 30, 2026

View reviewed changes

rosspeili and others added 3 commits May 30, 2026 12:37

Update check/nbformat

8c043e4

Co-authored-by: Michael Hucka <mhucka@google.com>

fix: use tensorflow_docs.tools.nbfmt for notebook checks (quantumlib#…

b52511c

…1274) The checker called a non-existent tensorflow_docs.tools.nbformat module. Align with Cirq by using nbfmt, regenerate lockfiles on current main, and format all tracked notebooks so CI can pass.

rosspeili force-pushed the feature/issue-1274-notebook-format-check branch from 39ff7df to b52511c Compare May 30, 2026 10:02

rosspeili requested a review from mhucka May 30, 2026 11:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature/issue 1274 notebook format check#1299

Feature/issue 1274 notebook format check#1299
rosspeili wants to merge 3 commits into
quantumlib:mainfrom
rosspeili:feature/issue-1274-notebook-format-check

rosspeili commented May 6, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

rosspeili commented May 17, 2026

Uh oh!

mhucka commented May 30, 2026 •

edited

Loading

Uh oh!

Uh oh!

mhucka May 30, 2026 •

edited

Loading

Uh oh!

rosspeili commented May 30, 2026 •

edited

Loading

Uh oh!

review-notebook-app Bot commented May 30, 2026

Uh oh!

rosspeili commented May 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

rosspeili commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

rosspeili commented May 17, 2026

Uh oh!

mhucka commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

mhucka May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rosspeili commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

review-notebook-app Bot commented May 30, 2026

Uh oh!

rosspeili commented May 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rosspeili commented May 6, 2026 •

edited

Loading

mhucka commented May 30, 2026 •

edited

Loading

mhucka May 30, 2026 •

edited

Loading

rosspeili commented May 30, 2026 •

edited

Loading