feat: bootstrap HowToLens repo from autolens_workspace tutorials

[Jammy2211]

Overview

Extract the howtolens tutorial series out of autolens_workspace into its own standalone repo (Jammy2211/HowToLens, to be transferred to PyAutoLabs org). This is sub-task 1 of 3 — follow-up issues will (2) clean up autolens_workspace to remove the migrated content and update cross-references, and (3) update PyAutoLens docs/URLs to point at the new repo. The same pattern will later be applied to HowToGalaxy and HowToFit.

Plan

• Scaffold a fresh HowToLens repo with the standard workspace layout (config/ dataset/ notebooks/ output/ scripts/).
• Copy scripts/howtolens/* and notebooks/howtolens/* from autolens_workspace verbatim (fresh copy, no git history preservation). Flatten one level — whole repo is HowToLens, so strip the howtolens/ sub-folder.
• Copy supporting files (config/, requirements.txt, runtime.txt) and author a fresh README.rst, CLAUDE.md, start_here.py, welcome.py, CITATIONS.rst, CODE_OF_CONDUCT.md, CONTRIBUTING.md, smoke_tests.txt.
• Commit zero .fits files — tutorials already simulate their own datasets at runtime via scripts/simulator/*.py.
• Add CI workflows: url_check.yml (same as autolens_workspace) and a smoke_tests.yml modeled on autolens_workspace_test, running the howtolens scripts under PyAuto fast/test-mode flags.
• Push to Jammy2211/HowToLens, then gh repo transfer Jammy2211/HowToLens PyAutoLabs and accept on the org side.

Detailed implementation plan

Affected Repositories

• HowToLens (new, primary — Jammy2211/HowToLens → PyAutoLabs/HowToLens after push)

autolens_workspace and PyAutoLens are untouched by this sub-task — their cleanup lives in sibling issues (2) and (3).

Work Classification

Workspace (new workspace-style repo)

Branch Survey

Repository	Current Branch	Dirty?
HowToLens	(new)	n/a — fresh clone into the task worktree

Suggested branch: feature/howtolens-bootstrap
Worktree root: ~/Code/PyAutoLabs-wt/howtolens-bootstrap/ (created later by /start_workspace)

No overlap with other active tasks (smoke-test-optimization, jax-likelihood-multi-parity, searches-minimal) — none of them touch HowToLens.

Implementation Steps

1. Clone Jammy2211/HowToLens into the task worktree root. Confirm it's effectively empty (0 KB disk usage per gh repo view).

2. Create top-level folder structure:

   HowToLens/
     config/         # copy from autolens_workspace/config/
     dataset/        # empty — tutorials generate .fits at runtime
     notebooks/      # populated in step 4
     output/         # .gitkeep only
     scripts/        # populated in step 3
     .github/workflows/
   

3. Copy scripts content — flatten one level:

   • autolens_workspace/scripts/howtolens/chapter_1_introduction/ → HowToLens/scripts/chapter_1_introduction/
   • Same pattern for chapter_2_lens_modeling/, chapter_3_search_chaining/, chapter_4_pixelizations/, chapter_optional/, simulator/.
   • Update internal path references in scripts from scripts/howtolens/simulator/... to scripts/simulator/....
   • Update dataset_path = Path("dataset") / "imaging" / "howtolens" → Path("dataset") / "imaging" (or keep sub-folder; decide during implementation to minimize script edits).

4. Copy notebooks content:

   • autolens_workspace/notebooks/howtolens/* → HowToLens/notebooks/* (flattened the same way).
   • Ideally regenerate via PyAutoBuild generate.py after the script edits in step 3 settle, rather than hand-editing .ipynb.

5. Copy supporting files from autolens_workspace and adapt:

   • config/ — copy whole tree.
   • requirements.txt, runtime.txt — copy as-is.
   • CITATIONS.rst, CODE_OF_CONDUCT.md, CONTRIBUTING.md — copy, update repo URL references.
   • welcome.py — copy and rewrite welcome text for HowToLens.
   • smoke_tests.txt — rewrite to list the howtolens smoke scripts.
   • .gitignore — copy from autolens_workspace.

6. Author new top-level README.rst by merging:

   • autolens_workspace/scripts/howtolens/README.rst (overview + chapter descriptions).
   • Usage/installation sections adapted from autolens_workspace/README.rst.
   • A "Relationship to autolens_workspace" section pointing users back to the main workspace.

7. Author CLAUDE.md modeled on autolens_workspace/CLAUDE.md, scoped to the HowToLens surface (chapter layout, build/test commands, PyAutoBuild integration).

8. Author start_here.py — short orientation script directing new users to scripts/chapter_1_introduction/tutorial_0_visualization.py.

9. CI: .github/workflows/url_check.yml — copy from autolens_workspace/.github/workflows/url_check.yml verbatim.

10. CI: .github/workflows/smoke_tests.yml — adapt autolens_workspace_test/.github/workflows/smoke_tests.yml:

    • Checkout PyAutoConf/Fit/Array/Galaxy/Lens.
    • Install with [optional] extras on 3.12, numba-only on 3.13.
    • Run the howtolens scripts via a run_smoke.py runner under PYAUTO_TEST_MODE=2 PYAUTO_SMALL_DATASETS=1 PYAUTO_FAST_PLOTS=1 PYAUTO_DISABLE_JAX=1.
    • Slack-notify on failure (same webhook pattern).

11. Smoke-test locally from the worktree root:

    PYAUTO_TEST_MODE=2 PYAUTO_SMALL_DATASETS=1 PYAUTO_FAST_PLOTS=1 \
      NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib \
      python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py

    At minimum confirm chapter 1 tutorials import and run end-to-end.

12. First commit + push to Jammy2211/HowToLens on feature/howtolens-bootstrap, then open a PR against main (the repo is essentially empty, so this is effectively a seed PR).

13. After merge, run gh repo transfer Jammy2211/HowToLens PyAutoLabs and accept the transfer. Note: PyAutoLabs/HowToLens URLs start working only after acceptance — sub-tasks 2 and 3 should hard-code the post-transfer URL.

Key Files

• HowToLens/README.rst — main landing page, new file
• HowToLens/CLAUDE.md — agent instructions, new file
• HowToLens/start_here.py — orientation script, new file
• HowToLens/scripts/chapter_*/ — migrated from autolens_workspace/scripts/howtolens/chapter_*/
• HowToLens/notebooks/chapter_*/ — migrated from autolens_workspace/notebooks/howtolens/chapter_*/
• HowToLens/.github/workflows/url_check.yml — CI
• HowToLens/.github/workflows/smoke_tests.yml — CI

Follow-up issues (do NOT handle here)

• Sub-task 2 (autolens_workspace cleanup): remove scripts/howtolens/, notebooks/howtolens/, update all howtolens-referencing files (10+ Python scripts, README.rst, start_here.py/.ipynb, CLAUDE.md, config/build/*.yaml).
• Sub-task 3 (PyAutoLens docs): update docs/index.rst toctree, howtolens/*.rst pages, README.rst, paper/paper.md, overview/overview_2_new_user_guide.rst, general/workspace.rst.

Original Prompt

Click to expand starting prompt

The howtolens jupyter notebook lectures are in autolens_workspace/scripts/howtolens (and notebook)

I want to make them their own GitHub repo, with their own continuous integration, following the same 
folder parts (config / dataset / notebooks / output / scripts) as other workspaces. Can you do this?
I have set up the GitHub repo:

https://github.com/Jammy2211/HowToLens

I forgot to put HowToLens in the PyAutoLabs organisation so can you do that as well.

You also need to make sure:

- The repo is set up and populated with descriptions of HowToLens that can be takenf rom all the existing workspace stuff.
- That existing workspace stuff is updated to point to this repo, including URL updates.

After this task. we will perform identical work with HowToGalaxy and HowToFit:

https://github.com/Jammy2211/HowToGalaxy
https://github.com/Jammy2211/HowToFit

Feel free to break this take down into many subprompts

[Jammy2211]

Bootstrap PR opened: PyAutoLabs/HowToLens#1

Covers step 1 of the three-part plan. After this merges and the repo is transferred to PyAutoLabs, the follow-up sub-tasks will be:

2. howtolens-workspace-cleanup — remove scripts/howtolens/ and notebooks/howtolens/ from this repo, update all cross-references.
3. howtolens-docs-update — update PyAutoLens docs (index.rst toctree, howtolens/*.rst, README.rst, paper.md, overview/*.rst, general/workspace.rst) to point at the new PyAutoLabs/HowToLens repo.

Plus one adjacent:

4. PyAutoBuild needs a howtolens project target registered in generate.py before /pre_build can build HowToLens notebooks.

Also: tutorials 0 and 7 of chapter 1 have pre-existing upstream bugs (missing Path import / missing auto-sim fallback). They're excluded from the initial smoke list and will need a content-alignment pass to fold into HowToLens's runtime-simulation conventions.