Restore fit-problem motivation and adaptive reconstruction in Chapter 3

README.md

@@ -95,10 +95,12 @@ for the chapter 1 tutorials listed with a `markdown` link below; every other tut
   - Tutorial 5: Data and Likelihoods — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_2_modeling/tutorial_5_data_and_likelihoods.ipynb))
   - Tutorial 6: Search Chaining — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_2_modeling/tutorial_6_search_chaining.ipynb))
   - Tutorial 7: Summary — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_2_modeling/tutorial_7_summary.ipynb))
-- **[Chapter 3: Pixelizations](scripts/chapter_3_pixelizations/README.md)** — Indexed mappings, inversions, regularization and MGE search chaining.
+- **[Chapter 3: Pixelizations](scripts/chapter_3_pixelizations/README.md)** — Mappings, Bayesian regularization, fit problems, adaptive reconstruction and MGE search chaining.
   - Tutorial 1: Pixelizations — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_1_pixelizations.ipynb))
   - Tutorial 2: Bayesian Regularization — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_2_bayesian_regularization.ipynb))
-  - Tutorial 3: Model Fit — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_3_model_fit.ipynb))
+  - Tutorial 3: Fit Problems — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_3_fit_problems.ipynb))
+  - Tutorial 4: Adaptive Reconstruction — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_4_adaptive_reconstruction.ipynb))
+  - Tutorial 5: Model Fit — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_5_model_fit.ipynb))
 
 - **[Chapter 4: Scaling Up Galaxies](scripts/chapter_4_scaling_up_galaxies/README.md)** — Extra galaxies, blended multi-galaxy systems, and cluster fields.
   - Tutorial 1: Extra Galaxies — ([Colab](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_galaxies/tutorial_1_extra_galaxies.ipynb))

llms-full.txt

@@ -41,11 +41,15 @@ AUTO-GENERATED by PyAutoHands — do not edit by hand; regenerate with generate.
 ## chapter_3_pixelizations
 
 - [Tutorial 1: Pixelizations, Mappers and Inversions](scripts/chapter_3_pixelizations/tutorial_1_pixelizations.py): Look at a resolved galaxy image. Its broad light distribution may follow a smooth bulge and disc, while smaller regions contain bright star-forming knots, off-centre clumps or irregular extensions. A model can capture the overall galaxy yet leave these features clearly visible in the residual image.
-  - Contents: The image and its coordinates, A brightness mesh, Following the mappings, An inversion, A model image, Using FitImaging
-- [Tutorial 2: Bayesian Regularization](scripts/chapter_3_pixelizations/tutorial_2_bayesian_regularization.py): (no summary in script docstring)
-  - Contents: Interpolation and our starting reconstruction., Reducing and increasing regularization., Bayesian evidence and a coefficient experiment., Inspecting the preferred reconstruction., Linear brightnesses and non-linear model choices., Comparing mesh resolutions.
-- [Tutorial 3: Model Fit](scripts/chapter_3_pixelizations/tutorial_3_model_fit.py): A pixelization can describe a galaxy without assigning an analytic centre and shape to every visible feature. However, analytic profiles remain useful when we want to describe its smooth components. In this tutorial we combine an MGE with a pixelization and use search chaining to put the smooth light model in place first.
-  - Contents: Dataset, Search 1, Search 2, Search 3, Interpretation
+  - Contents: The image and its coordinates, A brightness mesh, Following the mappings, An inversion, Keeping brightnesses non-negative, Where the image weakly constrains the mesh, A model image, Using FitImaging, Wrap Up
+- [Tutorial 2: Bayesian Regularization](scripts/chapter_3_pixelizations/tutorial_2_bayesian_regularization.py): Choose the regularization strength by comparing log evidences, then examine how mesh resolution changes that choice.
+  - Contents: Interpolation and Bayesian regularization, Interpolation and our starting reconstruction, Reducing regularization, Increasing regularization, Bayesian evidence, Exploring the regularization coefficient, Inspecting the preferred reconstruction, What is linear, and what requires a search?, Mesh resolution and regularization belong together, Wrap Up
+- [Tutorial 3: Fit Problems](scripts/chapter_3_pixelizations/tutorial_3_fit_problems.py): Investigate why compact galaxies can challenge mesh resolution and constant regularization even with a known PSF.
+  - Contents: When the best coefficient is not enough, Three progressively compact galaxies, Simulating the images, Reconstructing the galaxies, Finding the preferred regularization, Starting with the extended galaxy, Making the galaxy more compact, A very compact galaxy, Why the mesh becomes a limitation, Why one regularization coefficient becomes a compromise, Why maximizing the evidence does not remove the compromise, Wrap Up
+- [Tutorial 4: Adaptive Reconstruction](scripts/chapter_3_pixelizations/tutorial_4_adaptive_reconstruction.py): Combine Delaunay meshes, Hilbert brightness adaptation and adaptive Split regularization for directly observed galaxies.
+  - Contents: Adaptive galaxy reconstruction, Returning to the compact-galaxy problem, From image coordinates to a reconstruction mesh, Constructing the Delaunay galaxy mesh, Interpolating within a triangle, Regularization on an irregular mesh, Building an adapt image, Placing points with a Hilbert image mesh, Controlling the brightness weighting, Keeping resolution in the faint regions, Reconstructing with the Hilbert mesh, Comparing overlay and Hilbert reconstructions, Smoothing on an irregular mesh, Reconstructing with ConstantSplit, Allowing different smoothing strengths, Controlling the transition with `signal_scale`, Exploring the adaptive coefficients, Does adaptive regularization address the fit problem?, Wrap Up
+- [Tutorial 5: Model Fit](scripts/chapter_3_pixelizations/tutorial_5_model_fit.py): Tutorials 3 and 4 explored mesh resolution and adaptive smoothing using a galaxy reconstructed entirely on a mesh. We now return to the complementary question of how to combine a smooth analytic component with a pixelization. The rectangular mesh here keeps that decomposition experiment simple; inspect its residuals and revisit the adaptive choices from Tutorial 4 when the pixelized component needs more spatially varying resolution.
+  - Contents: Search 1: Fit the MGE, Search 2: Add the pixelization, Search 3: Refine both components, Wrap Up
 
 ## chapter_4_scaling_up_galaxies
 

llms.txt

@@ -26,7 +26,7 @@ real analysis?" below).
 
 - **Chapter 1 — Introduction** → [scripts/chapter_1_introduction/](scripts/chapter_1_introduction/): Galaxies from first principles: grids & galaxies, light profiles, simulating data, and fitting data. The conceptual foundation.
 - **Chapter 2 — Modeling** → [scripts/chapter_2_modeling/](scripts/chapter_2_modeling/): Fitting a galaxy model to data with a non-linear search — practicalities, difficult fits, linear profiles, data and likelihoods, and component-based search chaining.
-- **Chapter 3 — Pixelizations** → [scripts/chapter_3_pixelizations/](scripts/chapter_3_pixelizations/): Reconstructing galaxy structure on a mesh — indexed mappings, inversions, Bayesian regularization and combined MGE/pixelization search chaining.
+- **Chapter 3 — Pixelizations** → [scripts/chapter_3_pixelizations/](scripts/chapter_3_pixelizations/): Reconstructing galaxy structure on a mesh — indexed mappings, inversions, Bayesian regularization, fit problems, adaptive reconstruction and combined MGE/pixelization search chaining.
 - **Chapter 4 — Scaling Up Galaxies** → [scripts/chapter_4_scaling_up_galaxies/](scripts/chapter_4_scaling_up_galaxies/): Beyond a single galaxy — extra galaxies, blended multi-galaxy systems, and cluster fields.
 
 ## I want to understand…
@@ -38,7 +38,10 @@ real analysis?" below).
 - **My fit found a wrong (local-maxima) solution — what do I do?** → [scripts/chapter_2_modeling/tutorial_3_why_modeling_is_hard.py](scripts/chapter_2_modeling/tutorial_3_why_modeling_is_hard.py): Prior tuning, reducing complexity, and looking harder.
 - **What are linear light profiles / MGE?** → [scripts/chapter_2_modeling/tutorial_4_linear_profiles.py](scripts/chapter_2_modeling/tutorial_4_linear_profiles.py): Solving intensities linearly; the Multi-Gaussian Expansion basis.
 - **How do I model an image with two galaxies?** → [scripts/chapter_4_scaling_up_galaxies/tutorial_2_multi_galaxy.py](scripts/chapter_4_scaling_up_galaxies/tutorial_2_multi_galaxy.py): Joint fitting of blended galaxies and their degeneracies.
-- **How do I reconstruct irregular structure on a pixel grid?** → [scripts/chapter_3_pixelizations/tutorial_1_pixelizations.py](scripts/chapter_3_pixelizations/tutorial_1_pixelizations.py) through [tutorial_3_model_fit.py](scripts/chapter_3_pixelizations/tutorial_3_model_fit.py).
+- **How do I reconstruct irregular structure on a pixel grid?** → [scripts/chapter_3_pixelizations/tutorial_1_pixelizations.py](scripts/chapter_3_pixelizations/tutorial_1_pixelizations.py) through [tutorial_5_model_fit.py](scripts/chapter_3_pixelizations/tutorial_5_model_fit.py).
+
+- **Why does a regularized reconstruction still leave residuals?** → [tutorial_3_fit_problems.py](scripts/chapter_3_pixelizations/tutorial_3_fit_problems.py): Mesh resolution, concentrated light and the limits of smoothing.
+- **How can the mesh and smoothing follow galaxy brightness?** → [tutorial_4_adaptive_reconstruction.py](scripts/chapter_3_pixelizations/tutorial_4_adaptive_reconstruction.py): Hilbert sampling and adaptive regularization, compared using log evidence.
 
 ## Ready for real analysis?
 

notebooks/chapter_3_pixelizations/README.md

@@ -16,10 +16,13 @@ The reconstruction still depends on modelling choices, including the mesh, its r
 
 MGE and other analytic profiles remain useful for describing and measuring smooth galaxy components. Pixelizations complement them when more complicated structure needs to be represented, including in models that combine analytic components with a pixelized reconstruction.
 
-# Files
-
-- [Tutorial 1: Pixelizations](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_1_pixelizations.ipynb) — Meshes, indexed mappings, inversions and telescope blurring.
+The chapter moves from mappings and evidence-based regularization to the practical limits of a fixed mesh. We then
+explore brightness-guided mesh placement and adaptive smoothing, before fitting an MGE and a pixelization together.
 
-- [Tutorial 2: Bayesian Regularization](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_2_bayesian_regularization.ipynb) — Interpolation, smoothness priors, evidence and resolution experiments.
+# Files
 
-- [Tutorial 3: Model Fit](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_3_model_fit.ipynb) — An MGE fit followed by a combined MGE and pixelized model.
+- [Tutorial 1: Pixelizations](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_1_pixelizations.ipynb) — Mappings, inversions, positivity and telescope blurring.
+- [Tutorial 2: Bayesian Regularization](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_2_bayesian_regularization.ipynb) — The Goldilocks balance, log-evidence selection and mesh resolution.
+- [Tutorial 3: Fit Problems](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_3_fit_problems.ipynb) — Compact galaxies expose mesh-resolution and constant-smoothing limitations.
+- [Tutorial 4: Adaptive Reconstruction](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_4_adaptive_reconstruction.ipynb) — Delaunay/Hilbert mesh placement and adaptive Split regularization.
+- [Tutorial 5: Model Fit](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_3_pixelizations/tutorial_5_model_fit.ipynb) — MGE fitting, adding a pixelization and refining the combined model.

notebooks/chapter_3_pixelizations/tutorial_1_pixelizations.ipynb

@@ -53,17 +53,21 @@
     "\n",
     "__Contents__\n",
     "\n",
-    "- **The image and its coordinates:** Load and mask the data.\n",
-    "- **A brightness mesh:** Distinguish image indexes from mesh indexes.\n",
-    "- **Following the mappings:** Highlight which image pixels receive each mesh contribution.\n",
-    "- **An inversion:** Infer brightnesses, accounting for noise and telescope blurring.\n",
-    "- **A model image:** Inspect the reconstruction and residuals separately.\n",
-    "- **Using FitImaging:** Put these ingredients into a galaxy model.\n",
+    "- The image and its coordinates\n",
+    "- A brightness mesh\n",
+    "- Following the mappings\n",
+    "- An inversion\n",
+    "- Keeping brightnesses non-negative\n",
+    "- Where the image weakly constrains the mesh\n",
+    "- A model image\n",
+    "- Using FitImaging\n",
+    "- Wrap Up\n",
     "\n",
     "__The image and its coordinates__\n",
     "\n",
     "The simulator supplies a S\u00e9rsic bulge and exponential disc. The circular mask selects the image pixels used in the\n",
-    "fit. We use one sample per image pixel for the indexed illustrations; accurate scientific modelling should also\n",
+    "fit. It also affects the mesh extent: including distant blank sky spreads a fixed number of mesh points over a\n",
+    "larger area. Inspect the mask against the galaxy before deciding whether more mesh points are needed. We use one sample per image pixel for the indexed illustrations; accurate scientific modelling should also\n",
     "check image integration. Each unmasked pixel has a position and a flattened index. These indexes describe the data,\n",
     "not the separate mesh we are about to construct."
    ]
@@ -296,6 +300,54 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "__Keeping brightnesses non-negative__\n",
+    "\n",
+    "By default, the inversion constrains reconstructed brightnesses to be non-negative; zero is allowed. This prevents\n",
+    "it from explaining the observed image by adding negative galaxy light.\n",
+    "\n",
+    "Positivity and regularization do different jobs. Positivity restricts the allowed brightnesses, whereas\n",
+    "regularization discourages large differences between neighbours. Non-negative values can still fit noise, so the\n",
+    "positivity constraint does not remove the need for smoothing.\n",
+    "\n",
+    "__Where the image weakly constrains the mesh__\n",
+    "\n",
+    "Some mesh points contribute to many image pixels, while others have little direct support. We can sum the absolute\n",
+    "mapping weights for each mesh point and compare that support with its reconstructed brightness.\n",
+    "\n",
+    "The next cell counts effectively unmapped points and prints the five least-supported values. There may be no\n",
+    "exactly unmapped points in this example; the diagnostic does not assume otherwise."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "\n",
+    "mapping_support = np.sum(np.abs(np.asarray(mapper.mapping_matrix)), axis=0)\n",
+    "unsupported = np.flatnonzero(mapping_support <= 1.0e-12)\n",
+    "least_supported = np.argsort(mapping_support)[:5]\n",
+    "print(\"Mesh points with effectively zero mapping weight:\", len(unsupported))\n",
+    "for mesh_index in least_supported:\n",
+    "    print(\n",
+    "        f\"Mesh index {mesh_index}: total mapping weight={mapping_support[mesh_index]:.6g}, \"\n",
+    "        f\"reconstructed brightness={reconstruction[mesh_index]:.6g}\"\n",
+    "    )"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A point with no direct mapping cannot have its brightness determined directly by the image. Neighbouring values,\n",
+    "regularization, positivity and any boundary constraints can instead influence it. For weakly supported points,\n",
+    "both the data and those constraints matter.\n",
+    "\n",
+    "This weight sum is a geometric diagnostic, not a brightness uncertainty. It does not include image noise, PSF\n",
+    "blurring or correlations between inferred values. In particular, a finely sampled reconstruction does not give\n",
+    "independent measurements of features smaller than the telescope resolution.\n",
+    "\n",
     "__A model image__\n",
     "\n",
     "The brightness reconstruction lives on the mesh. Mapping it onto the image grid and convolving with the PSF\n",