|
| 1 | +- issue: (none — run end-to-end from a cloud session; the six PRs are the record) |
| 2 | +- completed: 2026-08-18 |
| 3 | +- prs: HowToFit#45, HowToGalaxy#66, HowToLens#70, autofit_workspace#138, |
| 4 | + autogalaxy_workspace#211, autolens_workspace#485 — all squash-merged 2026-08-18, |
| 5 | + every check green on each. |
| 6 | +- merge-commits: HowToFit `1a4e7132`, HowToGalaxy `d973bc57`, HowToLens `e0fbdf61`, |
| 7 | + autofit_workspace `fa55c438`, autogalaxy_workspace `47227c79`, autolens_workspace `c5960f69`. |
| 8 | +- summary: Full audit of the `# from auto* import setup_notebook; setup_notebook()` boilerplate |
| 9 | + across every notebook-generating repo. 39 scripts were missing it — HowToFit 3, HowToGalaxy 2, |
| 10 | + HowToLens 6, autofit_workspace 1, autogalaxy_workspace 5, autolens_workspace 22 — and all 39 |
| 11 | + were fixed with their generated notebooks updated to the uncommented form PyAutoHands emits. |
| 12 | + autocti_workspace was already clean (79 scripts, 0 missing). The line chdir's to the workspace |
| 13 | + root and enables inline plotting; without it a notebook that loads data by a relative path |
| 14 | + fails under nbconvert, which runs with CWD set to the notebook's own directory. |
| 15 | +- the only live breakage: `HowToLens/scripts/simulator/lens_x{2,3}.py`, which resolve |
| 16 | + `dataset_path = Path("dataset", ...)` against CWD and write FITS output there. Everything else |
| 17 | + in the sweep is prose-only or import-only and passed today for exactly the reason the original |
| 18 | + report predicted — they never load data by relative path. |
| 19 | +- the omissions were not policy: they sit alongside siblings in the SAME directory that do carry |
| 20 | + the line (`autolens_workspace/scripts/cluster/` has 6 without and 5 with). Anyone re-auditing |
| 21 | + should not read a missing line as a deliberate per-subtree exemption. |
| 22 | +- placement rule (two forms, both in the tree already): after the module docstring, OR after the |
| 23 | + `from auto* import jax_wrapper` line where a script has one — jax_wrapper must set the JAX |
| 24 | + environment before anything else. One outlier, |
| 25 | + `autolens_workspace/scripts/guides/units/mass_to_light_ratio_units.py`, opens on imports rather |
| 26 | + than a docstring; the line went at the top of the file, still ahead of every import. |
| 27 | +- SCOPE BOUNDARY worth keeping: `autoreduce_workspace` has 30 scripts and NONE carry the line, |
| 28 | + which looks alarming until you notice it has no `notebooks/` directory — nothing generates |
| 29 | + notebooks there, so the convention does not apply yet. Same for every `*_workspace_test` and |
| 30 | + `*_workspace_developer` repo (verified by tree listing, not assumption). If autoreduce_workspace |
| 31 | + ever starts generating notebooks, those 30 scripts need this sweep. |
| 32 | +- notebooks were NOT regenerated by PyAutoHands: it is not available in a cloud session, so the |
| 33 | + `.ipynb` files were patched directly to the exact shape the generator emits. Verified three ways |
| 34 | + before pushing — the edit reproduces already-correct sibling pairs byte-for-byte, |
| 35 | + `json.dumps(nb, indent=1)` round-trips every touched file unchanged, and every `.py` still |
| 36 | + parses. A real `generate.py` run should be a no-op on these; if it is not, that is the thing to |
| 37 | + look at first. |
| 38 | +- CRLF trap: `HowToFit/scripts/chapter_1_introduction/tutorial_1_models.py` is committed with CRLF |
| 39 | + line endings while everything around it is LF. A naive read/split/write rewrote all 547 lines as |
| 40 | + a whitespace-only diff. The fix preserves the file's existing terminator. Anything doing a |
| 41 | + mechanical sweep across these repos will hit this file. |
| 42 | +- pre-existing drift found, deliberately NOT touched: nine `start_here.ipynb` files in |
| 43 | + autolens_workspace and six in autogalaxy_workspace are stored with a JSON formatting that |
| 44 | + differs from the generator's `indent=1` output. Flagged in both PR bodies. Unrelated to this |
| 45 | + task, real, and unclaimed. |
| 46 | +- no pending-release gate applied to the three workspace legs: `setup_notebook` is long-shipped in |
| 47 | + the released libraries and is already called by every other example script in those repos, so |
| 48 | + there is no unreleased API for the library-first merge gate to guard. |
| 49 | +- adjacent but distinct: `draft/maintenance/workspaces/notebook_setup_notebook_drift_siblings.md` |
| 50 | + covers notebooks that carry the COMMENTED form and need regenerating. Different failure, still |
| 51 | + open, untouched here. |
| 52 | +- `HowToGalaxy/chapter_1_introduction/tutorial_4_methods.py`, named in the original report as |
| 53 | + missing, already carried the line — fixed before this audit ran. |
| 54 | + |
| 55 | +## Original prompt |
| 56 | + |
| 57 | +# Audit HowTo tutorials for missing setup_notebook() line |
| 58 | + |
| 59 | +Type: bug |
| 60 | +Target: HowToFit |
| 61 | +Repos: |
| 62 | +- @HowToFit |
| 63 | +- @HowToGalaxy |
| 64 | +- @HowToLens |
| 65 | +- @autofit_workspace |
| 66 | +- @autogalaxy_workspace |
| 67 | +- @autolens_workspace |
| 68 | +Difficulty: small |
| 69 | +Autonomy: safe |
| 70 | +Priority: normal |
| 71 | +Status: formalised |
| 72 | + |
| 73 | +Discovered during the batch-2b markdown rollout ([[markdown-example-renderings]]). |
| 74 | +Several HowTo tutorials are missing the standard |
| 75 | +`# from autoconf import setup_notebook; setup_notebook()` line that every other |
| 76 | +workspace/tutorial script carries (it chdir's to the workspace root + enables |
| 77 | +inline plotting). Without it, a tutorial that loads data via a relative path |
| 78 | +(or runs a simulator subprocess) FAILS when executed by nbconvert (which runs |
| 79 | +with CWD = the notebook's own directory), and only works interactively if the |
| 80 | +user happens to launch jupyter from the repo root. |
| 81 | + |
| 82 | +Confirmed missing in chapter_1_introduction alone: HowToFit start_here.py + |
| 83 | +tutorial_1_models.py; HowToGalaxy tutorial_4_methods.py; (HowToGalaxy |
| 84 | +tutorial_3_fitting.py + HowToLens tutorial_7_fitting.py were fixed in batch 2b's |
| 85 | +PRs since they blocked rendering). The 3 still-missing pass today only because |
| 86 | +they don't load data by relative path. |
| 87 | + |
| 88 | +Fix: audit ALL chapters of all three HowTo repos (and re-check the workspaces) |
| 89 | +for scripts lacking the setup_notebook line; add it right after the opening |
| 90 | +docstring, matching the sibling convention; regenerate the affected notebooks. |
| 91 | +Low-risk boilerplate consistency fix. |
| 92 | + |
| 93 | +## Audit result (2026-08-18) |
| 94 | + |
| 95 | +Every `.py` under `scripts/` — plus each HowTo repo's root `start_here.py` — was checked in the |
| 96 | +three HowTo repos and all five user-facing workspaces. 39 scripts were missing the line: |
| 97 | + |
| 98 | +| Repo | Missing | Notes | |
| 99 | +|---|---|---| |
| 100 | +| HowToFit | 3 | `chapter_1_introduction/{start_here,tutorial_1_models}.py`, root `start_here.py` | |
| 101 | +| HowToGalaxy | 2 | `chapter_2_modeling/tutorial_8_need_for_speed.py`, root `start_here.py` | |
| 102 | +| HowToLens | 6 | `chapter_2_lens_modeling/{tutorial_8_need_for_speed,tutorial_11_slam}.py`, `chapter_3_pixelizations/tutorial_9_model_fit.py`, `simulator/{lens_x2,lens_x3}.py`, root `start_here.py` | |
| 103 | +| autofit_workspace | 1 | `overview/overview_3_statistical_methods.py` | |
| 104 | +| autogalaxy_workspace | 5 | under `guides/`, `imaging/data_preparation/`, `interferometer/` | |
| 105 | +| autolens_workspace | 22 | mostly `cluster/*`, `guides/*` and feature `simulator.py` scripts | |
| 106 | +| autocti_workspace | 0 | clean | |
| 107 | + |
| 108 | +`tutorial_4_methods.py` in HowToGalaxy, named in the original report, already carries the line — |
| 109 | +it was fixed before this audit ran. |
| 110 | + |
| 111 | +The omissions are not a deliberate per-subtree policy: they sit alongside siblings in the same |
| 112 | +directory that do carry the line (e.g. `autolens_workspace/scripts/cluster/` has 6 without and 5 |
| 113 | +with). |
| 114 | + |
| 115 | +The two genuinely load-bearing cases are `HowToLens/scripts/simulator/lens_x{2,3}.py`, which write |
| 116 | +to a relative `dataset/` path; the rest are prose-only or import-only scripts that pass today for |
| 117 | +the reason the report gives. |
| 118 | + |
| 119 | +**Out of scope, deliberately:** `autoreduce_workspace` has 30 scripts and none carry the line, but |
| 120 | +it has no `notebooks/` directory — the convention does not apply there yet. Same for every |
| 121 | +`*_workspace_test` and `*_workspace_developer` repo (checked by tree listing; none generates |
| 122 | +notebooks). |
| 123 | + |
| 124 | +**Placement:** after the module docstring, or after the `from auto* import jax_wrapper` line where |
| 125 | +a script has one. One outlier — `autolens_workspace/scripts/guides/units/mass_to_light_ratio_units.py` |
| 126 | +opens on imports rather than a docstring, so the line went at the top of the file. |
| 127 | + |
| 128 | +**Notebooks:** patched by hand to the exact shape PyAutoHands emits (uncommented, same cell, |
| 129 | +`json.dumps(nb, indent=1)` round-trips byte-identically), because the generator is not available in |
| 130 | +a cloud session. A real `generate.py` run should be a no-op on these — confirm before merging. |
| 131 | + |
| 132 | +Branch `claude/howto-setup-notebook-audit-dm2j9e` in all six repos, one commit each: |
| 133 | +HowToFit#45, HowToGalaxy#66, HowToLens#70, autofit_workspace#138, autogalaxy_workspace#211, |
| 134 | +autolens_workspace#485. |
0 commit comments