Refresh current-course navigation and Lens notebook guidance

AGENTS.md

@@ -8,15 +8,14 @@ canonical, agent-agnostic instructions for this repo.
 ## Repository Structure
 
 - `scripts/` — Runnable Python tutorial scripts:
-  - `chapter_1_introduction/` — Grids, profiles, galaxies, ray-tracing, point sources, the lensing
-    formalism, data, fitting
-  - `chapter_2_lens_modeling/` — Non-linear searches, Bayesian inference, lens modeling, search
-    chaining, prior passing, automated pipelines
-  - `chapter_3_pixelizations/` — Pixelized source reconstruction, inversions, regularization, the
-    Bayesian formalism
+  - `chapter_1_introduction/` — Grids, profiles, galaxies, ray-tracing, point sources, data, fitting
+  - `chapter_2_lens_modeling/` — Non-linear searches, practicalities, difficult fits, linear profiles,
+    data and likelihoods, component-based search chaining and an introduction to SLaM
+  - `chapter_3_pixelizations/` — Pixelized source reconstruction, mappings, inversions, evidence-guided
+    regularization, borders, lens modeling, fit problems and adaptive reconstruction
   - `chapter_4_scaling_up_lensing/` — Extra galaxies, multi-galaxy lenses, scaling relations, group
     and cluster scales, weak lensing
-  - `chapter_optional/` — Alternative searches and advanced topics
+  - `chapter_optional/` — Alternative searches, runtime and historical prior passing
   - `simulator/` — Simulator scripts that generate the tutorial datasets at runtime
 - `notebooks/` — Jupyter versions, generated from `scripts/` (do not edit directly)
 - `config/` — PyAutoLens configuration YAML

README.md

@@ -1,8 +1,8 @@
 # HowToLens
 
-[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/start_here.ipynb)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/start_here.ipynb)
 
-[Start Here on Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/start_here.ipynb) |
+[Start Here on Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/start_here.ipynb) |
 [Installation Guide](https://pyautolens.readthedocs.io/en/latest/installation/overview.html) |
 [PyAutoLens readthedocs](https://pyautolens.readthedocs.io/en/latest/index.html) |
 [Browse Chapter 1 With Images](markdown/README.md) |
@@ -79,11 +79,11 @@ output figures inline. Nothing runs and nothing installs — you just read it. T
 skimming a tutorial before running it, or for reading on a phone. Markdown pages currently exist only
 for the chapter 1 tutorials listed with a `markdown` link below; every other tutorial is Colab-only.
 
-**[Start Here](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/start_here.ipynb)** — a one-page overview of the whole series.
+**[Start Here](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/start_here.ipynb)** — a one-page overview of the whole series.
 
 - **[Chapter 1: Introduction](scripts/chapter_1_introduction/README.md)** — Grids, light and mass profiles, galaxies, ray-tracing, point sources, the lensing formalism, data, and fitting.
-  - Tutorial 0: Visualization — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_0_visualization.ipynb) / [markdown](markdown/chapter_1_introduction/tutorial_0_visualization.md))
-  - Tutorial 1: Grids and Galaxies — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_1_grids_and_galaxies.ipynb) / [markdown](markdown/chapter_1_introduction/tutorial_1_grids_and_galaxies.md))
+  - Tutorial 0: Visualization — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_0_visualization.ipynb) / [markdown](markdown/chapter_1_introduction/tutorial_0_visualization.md))
+  - Tutorial 1: Grids and Galaxies — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_1_grids_and_galaxies.ipynb) / [markdown](markdown/chapter_1_introduction/tutorial_1_grids_and_galaxies.md))
   - Tutorial 2: Ray Tracing — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_2_ray_tracing.ipynb) / [markdown](markdown/chapter_1_introduction/tutorial_2_ray_tracing.md))
   - Tutorial 3: More Ray Tracing — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_3_more_ray_tracing.ipynb) / [markdown](markdown/chapter_1_introduction/tutorial_3_more_ray_tracing.md))
   - Tutorial 4: Point Sources — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_4_point_sources.ipynb) / [markdown](markdown/chapter_1_introduction/tutorial_4_point_sources.md))
@@ -106,12 +106,12 @@ for the chapter 1 tutorials listed with a `markdown` link below; every other tut
   - Tutorial 5 Fit Problems — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_3_pixelizations/tutorial_5_fit_problems.ipynb))
   - Tutorial 6 Adaptive Reconstruction — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_3_pixelizations/tutorial_6_adaptive_reconstruction.ipynb))
 - **[Chapter 4: Scaling Up Lensing](scripts/chapter_4_scaling_up_lensing/README.md)** — Extra galaxies, multi-galaxy lenses, scaling relations, group and cluster scales, and weak lensing.
-  - Tutorial 1: Extra Galaxies — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_1_extra_galaxies.ipynb))
-  - Tutorial 2: Multi Galaxy — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_2_multi_galaxy.ipynb))
-  - Tutorial 3: Scaling Relation — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_3_scaling_relation.ipynb))
-  - Tutorial 4: Group Scale — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_4_group_scale.ipynb))
-  - Tutorial 5: Cluster Scale — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_5_cluster_scale.ipynb))
-  - Tutorial 6: Weak Lensing — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_6_weak_lensing.ipynb))
+  - Tutorial 1: Extra Galaxies — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_1_extra_galaxies.ipynb))
+  - Tutorial 2: Multi Galaxy — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_2_multi_galaxy.ipynb))
+  - Tutorial 3: Scaling Relation — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_3_scaling_relation.ipynb))
+  - Tutorial 4: Group Scale — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_4_group_scale.ipynb))
+  - Tutorial 5: Cluster Scale — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_5_cluster_scale.ipynb))
+  - Tutorial 6: Weak Lensing — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_6_weak_lensing.ipynb))
 - **[Optional Tutorials](scripts/chapter_optional/README.md)** — Search methods, runtime and historical workflows.
   - [Need for Speed](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_optional/tutorial_need_for_speed.ipynb) — Computation, batching and estimating runtime.
   - [Historical Prior Passing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_optional/tutorial_prior_passing.ipynb) — An optional runnable example of prior passing using model_centred, a technique central to older workflows.

llms.txt

@@ -25,8 +25,8 @@ analysis?" below).
 ## The learning path (chapters in order)
 
 - **Chapter 1 — Introduction** → [scripts/chapter_1_introduction/](scripts/chapter_1_introduction/): Lensing from first principles: grids & galaxies, ray tracing, simulating data, and fitting data. The conceptual foundation everything else builds on.
-- **Chapter 2 — Lens Modeling** → [scripts/chapter_2_lens_modeling/](scripts/chapter_2_lens_modeling/): How to fit a lens model to data with a non-linear search — parameter spaces, priors, dealing with failure, linear light profiles, masking, and reading results.
-- **Chapter 3 — Pixelizations** → [scripts/chapter_3_pixelizations/](scripts/chapter_3_pixelizations/): Reconstructing the source on a pixel-grid instead of with light profiles — mappers, inversions, Bayesian regularization, the Bayesian formalism, borders, and adaptive meshes.
+- **Chapter 2 — Lens Modeling** → [scripts/chapter_2_lens_modeling/](scripts/chapter_2_lens_modeling/): How to fit a lens model to data with a non-linear search — parameter spaces, priors, difficult fits, linear light profiles, data and likelihoods, and component-based search chaining.
+- **Chapter 3 — Pixelizations** → [scripts/chapter_3_pixelizations/](scripts/chapter_3_pixelizations/): Reconstructing the source on a pixel-grid instead of with light profiles — mappers, inversions, evidence-guided regularization, borders, lens modeling, fit problems and adaptive reconstruction.
 - **Chapter 4 — Scaling Up Lensing** → [scripts/chapter_4_scaling_up_lensing/](scripts/chapter_4_scaling_up_lensing/): Beyond a single lens galaxy — extra galaxies, multi-galaxy lenses, scaling relations, group and cluster scales, and weak lensing.
 
 ## I want to understand…
@@ -39,6 +39,10 @@ analysis?" below).
 - **What are linear light profiles / MGE?** → [scripts/chapter_2_lens_modeling/tutorial_4_linear_profiles.py](scripts/chapter_2_lens_modeling/tutorial_4_linear_profiles.py): Solving intensities linearly; the Multi-Gaussian Expansion basis.
 - **How do I chain searches / what is SLaM?** → [scripts/chapter_2_lens_modeling/tutorial_6_search_chaining.py](scripts/chapter_2_lens_modeling/tutorial_6_search_chaining.py), including its SLaM introduction.
 - **How do I reconstruct a complex source on a pixel grid?** → [scripts/chapter_3_pixelizations/tutorial_1_pixelizations.py](scripts/chapter_3_pixelizations/tutorial_1_pixelizations.py) through [tutorial_2_bayesian_regularization.py](scripts/chapter_3_pixelizations/tutorial_2_bayesian_regularization.py).
+- **How do I choose the regularization strength?** → [tutorial_2_bayesian_regularization.py](scripts/chapter_3_pixelizations/tutorial_2_bayesian_regularization.py): Compare log evidences and inspect how mesh resolution affects the preferred coefficient.
+- **Why does a regularized reconstruction still leave residuals?** → [tutorial_5_fit_problems.py](scripts/chapter_3_pixelizations/tutorial_5_fit_problems.py): Compact sources expose limitations of mesh resolution and constant regularization, even with the correct mass model.
+- **How can the mesh and smoothing follow source brightness?** → [tutorial_6_adaptive_reconstruction.py](scripts/chapter_3_pixelizations/tutorial_6_adaptive_reconstruction.py): Delaunay meshes, Hilbert brightness adaptation and adaptive Split regularization.
+- **How do I fit lens mass with a pixelized source?** → [tutorial_4_lens_modeling.py](scripts/chapter_3_pixelizations/tutorial_4_lens_modeling.py): Search chaining and the positions likelihood penalty introduced in chapter 2 tutorial 5.
 - **How do I model lenses with many galaxies, groups, clusters or weak lensing?** → [scripts/chapter_4_scaling_up_lensing/tutorial_1_extra_galaxies.py](scripts/chapter_4_scaling_up_lensing/tutorial_1_extra_galaxies.py) through [tutorial_6_weak_lensing.py](scripts/chapter_4_scaling_up_lensing/tutorial_6_weak_lensing.py).
 
 ## Ready for real analysis?

notebooks/README.md

@@ -6,10 +6,11 @@ a strong lens.
 - `chapter_1_introduction`: An introduction to strong gravitational lensing and **PyAutolens**.
 - `chapter_2_lens_modeling`: How to model strong lenses, including a primer on Bayesian non-linear analysis
   and non-linear search chaining.
-- `chapter_3_pixelizations`: How to perform pixelized reconstructions of the source-galaxy.
+- `chapter_3_pixelizations`: Reconstruct complex source light, choose regularization using Bayesian
+  evidence, diagnose fit problems and adapt the mesh and smoothing.
 - `chapter_4_scaling_up_lensing`: How to scale lens modeling up to extra galaxies, multi-galaxy lenses,
   scaling relations, groups, clusters and weak lensing.
-- `chapter_optional`: Optional tutorials.
+- `chapter_optional`: Alternative searches, runtime and historical prior passing.
 - `simulator`: Scripts used to simulate the strong lens datasets fitted throughout the **HowToLens** lectures.
 
 # Full Explanation
@@ -110,18 +111,16 @@ fit CCD imaging data of a strong gravitational lens with a lens model. At the en
 
 **Using an inversion to perform a pixelized source reconstruction**
 
-In chapter 3, we'll learn how to reconstruct the lensed source galaxy using a pixel-grid, ensuring that we can fit an
-accurate lens model to sources with complex and irregular morphologies. You'll learn how to:
-
-1. Pixelize a source-plane into a set of source-plane pixels defined by mappings to image pixels.
-2. Perform a linear inversion on this source-plane pixelization to reconstruct the source's light.
-3. Apply a smoothness prior on the source reconstruction, called regularization.
-4. Apply smoothing within a Bayesian framework to objectively quantify the source reconstruction's complexity.
-5. Write down the linear algebra and Bayesian evidence equations that underpin the whole framework.
-6. Define a border in the source-plane to prevent pixels tracing outside the source reconstruction.
-7. Use alternative pixelizations, for example a Voronoi mesh whose pixels adapt to the lens's mass model
-   or to the source's own brightness, alongside adaptive regularization schemes.
-8. Use these features to fit a lens model via non-linear searches.
+In chapter 3, we'll reconstruct complex source light using a pixel-grid, compare reconstructions using Bayesian
+evidence, and investigate where the mesh and smoothing limit the fit. You'll learn how to:
+
+1. Connect reconstruction mesh points to image pixels through mappings.
+2. Solve for the source's brightness using a linear inversion.
+3. Apply regularization and compare log evidences to choose its strength.
+4. Explore how masks and border relocation affect source-mesh extent and resolution.
+5. Fit lens mass and foreground light with a pixelized source using search chaining and a positions likelihood penalty.
+6. Diagnose compact-source fit problems that remain after choosing the regularization coefficient.
+7. Combine Delaunay meshes, Hilbert brightness adaptation and adaptive Split regularization in a chained lens fit.
 
 # OVERVIEW OF CHAPTER 4 (Advanced)
 

notebooks/chapter_1_introduction/README.md

@@ -4,9 +4,9 @@ In chapter 1, we introduce you to strong gravitational lensing and the core **Py
 
 # Files
 
-- [Tutorial 0: Visualization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_0_visualization.ipynb) — Setting up **PyAutoLens**'s visualization library.
+- [Tutorial 0: Visualization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_0_visualization.ipynb) — Setting up **PyAutoLens**'s visualization library.
 
-- [Tutorial 1: Grids And Galaxies](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_1_grids_and_galaxies.ipynb) — Using grids of (y,x) coordinates with galaxies made up of light profiles.
+- [Tutorial 1: Grids And Galaxies](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_1_grids_and_galaxies.ipynb) — Using grids of (y,x) coordinates with galaxies made up of light profiles.
 
 - [Tutorial 2: Ray Tracing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_2_ray_tracing.ipynb) — Using grids, galaxies and mass profiles to perform strong lens ray-tracing.