feat: rectangular mesh split — Bilinear default everywhere, RTU documented as advanced

config/priors/mesh/rectangular_adapt_density.yaml → config/priors/mesh/rectangular_bilinear_adapt_density.yaml

@@ -1,21 +1,21 @@
-RectangularAdaptDensity:
-  shape_0:
-    type: Uniform
-    lower_limit: 20.0
-    upper_limit: 45.0
-    width_modifier:
-      type: Absolute
-      value: 8.0
-    limits:
-      lower: 3.0
-      upper: inf
-  shape_1:
-    type: Uniform
-    lower_limit: 20.0
-    upper_limit: 45.0
-    width_modifier:
-      type: Absolute
-      value: 8.0
-    limits:
-      lower: 3.0
+RectangularBilinearAdaptDensity:
+  shape_0:
+    type: Uniform
+    lower_limit: 20.0
+    upper_limit: 45.0
+    width_modifier:
+      type: Absolute
+      value: 8.0
+    limits:
+      lower: 3.0
+      upper: inf
+  shape_1:
+    type: Uniform
+    lower_limit: 20.0
+    upper_limit: 45.0
+    width_modifier:
+      type: Absolute
+      value: 8.0
+    limits:
+      lower: 3.0
       upper: inf

config/priors/mesh/rectangular_adapt_image.yaml → config/priors/mesh/rectangular_bilinear_adapt_image.yaml

@@ -1,40 +1,40 @@
-RectangularAdaptImage:
-  shape_0:
-    type: Uniform
-    lower_limit: 20.0
-    upper_limit: 45.0
-    width_modifier:
-      type: Absolute
-      value: 8.0
-    limits:
-      lower: 3.0
-      upper: inf
-  shape_1:
-    type: Uniform
-    lower_limit: 20.0
-    upper_limit: 45.0
-    width_modifier:
-      type: Absolute
-      value: 8.0
-    limits:
-      lower: 3.0
-      upper: inf
-  weight_power:
-    type : Uniform
-    lower_limit: 0.0
-    upper_limit: 10.0
-    width_modifier:
-      type: Absolute
-      value: 2.0
-    limits:
-      lower: -100.0
-      upper: 100.0
-  weight_floor:
-    type: LogUniform
-    lower_limit: 0.00001
-    upper_limit: 1.0
-    width_modifier:
-      type: Absolute
-    limits:
-      lower: 0.0
+RectangularBilinearAdaptImage:
+  shape_0:
+    type: Uniform
+    lower_limit: 20.0
+    upper_limit: 45.0
+    width_modifier:
+      type: Absolute
+      value: 8.0
+    limits:
+      lower: 3.0
+      upper: inf
+  shape_1:
+    type: Uniform
+    lower_limit: 20.0
+    upper_limit: 45.0
+    width_modifier:
+      type: Absolute
+      value: 8.0
+    limits:
+      lower: 3.0
+      upper: inf
+  weight_power:
+    type : Uniform
+    lower_limit: 0.0
+    upper_limit: 10.0
+    width_modifier:
+      type: Absolute
+      value: 2.0
+    limits:
+      lower: -100.0
+      upper: 100.0
+  weight_floor:
+    type: LogUniform
+    lower_limit: 0.00001
+    upper_limit: 1.0
+    width_modifier:
+      type: Absolute
+    limits:
+      lower: 0.0
       upper: inf

config/priors/mesh/rectangular_rtu_adapt_density.yaml

@@ -0,0 +1,21 @@
+RectangularRTUAdaptDensity:
+  shape_0:
+    type: Uniform
+    lower_limit: 20.0
+    upper_limit: 45.0
+    width_modifier:
+      type: Absolute
+      value: 8.0
+    limits:
+      lower: 3.0
+      upper: inf
+  shape_1:
+    type: Uniform
+    lower_limit: 20.0
+    upper_limit: 45.0
+    width_modifier:
+      type: Absolute
+      value: 8.0
+    limits:
+      lower: 3.0
+      upper: inf

config/priors/mesh/rectangular_rtu_adapt_image.yaml

@@ -0,0 +1,40 @@
+RectangularRTUAdaptImage:
+  shape_0:
+    type: Uniform
+    lower_limit: 20.0
+    upper_limit: 45.0
+    width_modifier:
+      type: Absolute
+      value: 8.0
+    limits:
+      lower: 3.0
+      upper: inf
+  shape_1:
+    type: Uniform
+    lower_limit: 20.0
+    upper_limit: 45.0
+    width_modifier:
+      type: Absolute
+      value: 8.0
+    limits:
+      lower: 3.0
+      upper: inf
+  weight_power:
+    type : Uniform
+    lower_limit: 0.0
+    upper_limit: 10.0
+    width_modifier:
+      type: Absolute
+      value: 2.0
+    limits:
+      lower: -100.0
+      upper: 100.0
+  weight_floor:
+    type: LogUniform
+    lower_limit: 0.00001
+    upper_limit: 1.0
+    width_modifier:
+      type: Absolute
+    limits:
+      lower: 0.0
+      upper: inf

llms-full.txt

@@ -312,9 +312,9 @@ AUTO-GENERATED by PyAutoHands — do not edit by hand; regenerate with generate.
   - Contents: Dataset Paths, Simulate, Ray Tracing, Output, Visualize, Tracer json
 - [Data Preparation: Datacube](scripts/interferometer/features/datacube/data_preparation.py): Most users come to datacube modeling with a single 4D FITS file from CASA, with shape ``(n_pol, n_chan, n_vis, 2)`` — for example, an ALMA observation of a CO emission line might be ``(2, 34, 16984, 2)``: two polarisations, 34 spectral channels, ~17k visibilities per channel, real/imag.
   - Contents: What ALMA Gives You, Polarisation Handling, Canonical 3D Shape, Shared vs Per-Channel uv_wavelengths / noise_map, 3D-FITS Loader, Worked Example
-- [Modeling: Datacube — Delaunay Source](scripts/interferometer/features/datacube/delaunay.py): This script fits a datacube — a list of `Interferometer` channels — with a single shared lens model and a per-channel **Delaunay-pixelized** source reconstruction. It is the Delaunay sibling of `modeling.py`, which fits the same cube with a `RectangularAdaptDensity` mesh.
+- [Modeling: Datacube — Delaunay Source](scripts/interferometer/features/datacube/delaunay.py): This script fits a datacube — a list of `Interferometer` channels — with a single shared lens model and a per-channel **Delaunay-pixelized** source reconstruction. It is the Delaunay sibling of `modeling.py`, which fits the same cube with a `RectangularBilinearAdaptDensity` mesh.
   - Contents: Mask, Dataset, Dataset Auto-Simulation, Dataset Loading, Sparse Operators, Positions, Settings, Image Mesh, Edge Zeroing, Adapt Images, Model, Per-Channel Analyses, FactorGraph, Search, Model Fit, Wrap Up
-- [__Log Likelihood Function: Datacube__](scripts/interferometer/features/datacube/likelihood_function.py): This script provides a step-by-step guide of the **PyAutoLens** `log_likelihood_function` used to fit a **datacube** — a list of N per-channel `Interferometer` objects sharing a single lens model — with a per-channel pixelized source reconstruction (specifically a `RectangularAdaptDensity` mesh and `Constant` regularization scheme).
+- [__Log Likelihood Function: Datacube__](scripts/interferometer/features/datacube/likelihood_function.py): This script provides a step-by-step guide of the **PyAutoLens** `log_likelihood_function` used to fit a **datacube** — a list of N per-channel `Interferometer` objects sharing a single lens model — with a per-channel pixelized source reconstruction (specifically a `RectangularBilinearAdaptDensity` mesh and `Constant` regularization scheme).
   - Contents: Comparison, Simplifications, Prerequisites, Mesh Shape, Mask, Dataset, Lens Galaxy, Source Galaxy Pixelization and Regularization, One Channel Walkthrough, Across All Channels, Fit, Lens Modeling, Log Likelihood Function: Source Code Speed Up, Wrap Up
 - [Modeling: Datacube](scripts/interferometer/features/datacube/modeling.py): This script fits a list of `Interferometer` channels — a "datacube" — with a single shared lens model and a per-channel pixelized source reconstruction. Each channel is an independent `Interferometer` dataset; the `af.FactorGraphModel` ties them together by feeding the same lens parameters into every channel's `AnalysisInterferometer.log_likelihood_function` and summing the per-channel log-evidences.
   - Contents: Mask, Dataset, Dataset Auto-Simulation, Dataset Loading, Sparse Operators, Settings, Mesh Shape, Model, Per-Channel Analyses, FactorGraph, Search, Model Fit, Wrap Up

scripts/group/features/advanced/double_source_plane_lens/slam.py

@@ -696,7 +696,7 @@ def source_pix_2(
     source_lp_result_1=source_lp_result_1,
     source_lp_result_2=source_lp_result_2,
     redshift_source_1=redshift_source_1,
-    mesh_init=af.Model(al.mesh.RectangularAdaptDensity, shape=mesh_shape),
+    mesh_init=af.Model(al.mesh.RectangularBilinearAdaptDensity, shape=mesh_shape),
     regularization_init=al.reg.Adapt,
 )
 
@@ -705,7 +705,7 @@ def source_pix_2(
     dataset=dataset,
     source_lp_result_2=source_lp_result_2,
     source_pix_result_1_source_0=source_pix_result_1_source_0,
-    mesh_init=af.Model(al.mesh.RectangularAdaptDensity, shape=mesh_shape),
+    mesh_init=af.Model(al.mesh.RectangularBilinearAdaptDensity, shape=mesh_shape),
     regularization_init=al.reg.Adapt,
 )
 
@@ -715,6 +715,6 @@ def source_pix_2(
     source_lp_result_2=source_lp_result_2,
     source_pix_result_1_source_0=source_pix_result_1_source_0,
     source_pix_result_1_source_1=source_pix_result_1_source_1,
-    mesh=af.Model(al.mesh.RectangularAdaptImage, shape=mesh_shape),
+    mesh=af.Model(al.mesh.RectangularBilinearAdaptImage, shape=mesh_shape),
     regularization=al.reg.Adapt,
 )

scripts/group/features/advanced/mass_stellar_dark/slam.py

@@ -537,7 +537,7 @@ def mass_light_dark(
     settings_search=settings_search,
     dataset=dataset,
     source_lp_result=source_lp_result,
-    mesh_init=af.Model(al.mesh.RectangularAdaptDensity, shape=mesh_shape),
+    mesh_init=af.Model(al.mesh.RectangularBilinearAdaptDensity, shape=mesh_shape),
     regularization_init=al.reg.Adapt,
 )
 
@@ -556,7 +556,7 @@ def mass_light_dark(
     dataset=dataset,
     source_lp_result=source_lp_result,
     source_pix_result_1=source_pix_result_1,
-    mesh=af.Model(al.mesh.RectangularAdaptImage, shape=mesh_shape),
+    mesh=af.Model(al.mesh.RectangularBilinearAdaptImage, shape=mesh_shape),
     regularization=al.reg.Adapt,
 )
 

scripts/group/features/advanced/subhalo/detect/start_here.py

@@ -808,7 +808,7 @@ def subhalo_refine(
     settings_search=settings_search,
     dataset=dataset,
     source_lp_result=source_lp_result,
-    mesh_init=af.Model(al.mesh.RectangularAdaptDensity, shape=mesh_shape),
+    mesh_init=af.Model(al.mesh.RectangularBilinearAdaptDensity, shape=mesh_shape),
     regularization_init=al.reg.Adapt,
 )
 
@@ -830,7 +830,7 @@ def subhalo_refine(
     dataset=dataset,
     source_lp_result=source_lp_result,
     source_pix_result_1=source_pix_result_1,
-    mesh=af.Model(al.mesh.RectangularAdaptImage, shape=mesh_shape),
+    mesh=af.Model(al.mesh.RectangularBilinearAdaptImage, shape=mesh_shape),
     regularization=al.reg.Adapt,
 )
 

scripts/group/features/pixelization/adaptive.py

@@ -28,7 +28,7 @@
 
 Two key adaptive classes are used:
 
- - `RectangularAdaptImage` mesh: adapts the rectangular source-pixel upsampling to the source's unlensed
+ - `RectangularBilinearAdaptImage` mesh: adapts the rectangular source-pixel upsampling to the source's unlensed
    morphology. More rectangular pixels are placed where the source is located, even in low magnification
    regions.
 
@@ -232,7 +232,7 @@
 
 pixelization = af.Model(
     al.Pixelization,
-    mesh=al.mesh.RectangularAdaptDensity(shape=mesh_shape),
+    mesh=al.mesh.RectangularBilinearAdaptDensity(shape=mesh_shape),
     regularization=al.reg.Constant,
 )
 
@@ -266,7 +266,7 @@
 
 Search 3 uses the adaptive pixelization classes:
 
- - `RectangularAdaptImage` mesh: adapts pixel density to the source morphology.
+ - `RectangularBilinearAdaptImage` mesh: adapts pixel density to the source morphology.
  - `Adapt` regularization: adapts smoothing strength to the source brightness.
 
 The lens mass is fixed from search 2 to ensure the adaptation is performed quickly.
@@ -290,7 +290,7 @@
 
 pixelization_3 = af.Model(
     al.Pixelization,
-    mesh=al.mesh.RectangularAdaptImage(shape=mesh_shape),
+    mesh=al.mesh.RectangularBilinearAdaptImage(shape=mesh_shape),
     regularization=al.reg.Adapt,
 )
 
@@ -399,7 +399,7 @@
 Key points:
  - Adaptive pixelizations are set up via search chaining: parametric fit -> constant pixelization -> adaptive.
  - The adapt_data is the lens-subtracted image, so accurate light modeling of ALL group galaxies is essential.
- - `RectangularAdaptImage` concentrates source pixels where the source is brightest.
+ - `RectangularBilinearAdaptImage` concentrates source pixels where the source is brightest.
  - `Adapt` regularization varies smoothing based on source brightness.
  - The SLaM pipeline (see `group/features/pixelization/slam.py`) automates this entire process.
 """

scripts/group/features/pixelization/cpu_fast_modeling.py

@@ -196,7 +196,7 @@
     ),
 )
 
-mesh = al.mesh.RectangularAdaptDensity(shape=mesh_shape)
+mesh = al.mesh.RectangularBilinearAdaptDensity(shape=mesh_shape)
 regularization = al.reg.Constant(coefficient=1.0)
 
 pixelization = al.Pixelization(mesh=mesh, regularization=regularization)
@@ -284,7 +284,7 @@
 
 pix = af.Model(
     al.Pixelization,
-    mesh=al.mesh.RectangularAdaptDensity(shape=mesh_shape),
+    mesh=al.mesh.RectangularBilinearAdaptDensity(shape=mesh_shape),
     regularization=al.reg.Constant,
 )
 

scripts/group/features/pixelization/slam.py

@@ -285,7 +285,7 @@ def source_lp_1(
 rectangular adaptive pixelization with `Adapt` regularization.
 
 Key pixelization choices:
- - `al.mesh.RectangularAdaptDensity`: a rectangular mesh whose cell density adapts to the source brightness.
+ - `al.mesh.RectangularBilinearAdaptDensity`: a rectangular mesh whose cell density adapts to the source brightness.
  - Fixed `mesh_shape = (28, 28)` pixels, chosen to match data resolution.
  - `al.reg.Adapt`: adaptive regularization that varies smoothing based on source brightness.
    Rectangular meshes use `Adapt` (not `AdaptSplit`, which is reserved for irregular meshes).
@@ -359,10 +359,10 @@ def source_pix_1(
         else None
     )
 
-    # Source: RectangularAdaptDensity mesh with Adapt regularization.
+    # Source: RectangularBilinearAdaptDensity mesh with Adapt regularization.
     pixelization = af.Model(
         al.Pixelization,
-        mesh=af.Model(al.mesh.RectangularAdaptDensity, shape=mesh_shape),
+        mesh=af.Model(al.mesh.RectangularBilinearAdaptDensity, shape=mesh_shape),
         regularization=af.Model(al.reg.Adapt),
     )
 
@@ -435,7 +435,7 @@ def source_pix_2(
 
     pixelization = af.Model(
         al.Pixelization,
-        mesh=af.Model(al.mesh.RectangularAdaptImage, shape=mesh_shape),
+        mesh=af.Model(al.mesh.RectangularBilinearAdaptImage, shape=mesh_shape),
         regularization=af.Model(al.reg.Adapt),
     )
 

scripts/group/features/pixelization/source_science.py

@@ -153,7 +153,7 @@
 mesh_pixels_yx = 28
 mesh_shape = (mesh_pixels_yx, mesh_pixels_yx)
 
-mesh = al.mesh.RectangularAdaptDensity(shape=mesh_shape)
+mesh = al.mesh.RectangularBilinearAdaptDensity(shape=mesh_shape)
 regularization = al.reg.Constant(coefficient=1.0)
 
 pixelization = al.Pixelization(mesh=mesh, regularization=regularization)

scripts/group/slam.py

@@ -424,7 +424,7 @@ def source_lp_1(
 __SOURCE PIX PIPELINE 1__
 
 Equivalent to `source_pix_1` in `slam_start_here.py`, except a Hilbert image mesh is used
-instead of `RectangularAdaptDensity`, with edge-point padding of 30 pixels. The Hilbert pixel
+instead of `RectangularBilinearAdaptDensity`, with edge-point padding of 30 pixels. The Hilbert pixel
 count is set by `al.model_util.hilbert_pixels_from_pixel_scale`.
 
 Pixelization over-sampling is signal-adaptive: pixels above the S/N threshold use sub-size 4,

scripts/guides/modeling/searches.py

@@ -153,10 +153,13 @@
   is often found late, and a long likelihood plateau is a regularization mode, not convergence. `batch_size`
   (e.g. 4) bounds the memory of the batched gradient, which pixelized models need.
 
-For the rectangular kernel-CDF meshes one further setting matters: a sharp `bandwidth` (e.g. 0.1) gives the mesh
-narrow gradient support that can stall descent, whereas the default `bandwidth=1.0` searches on a smoother
-likelihood at only a small cost in final fit quality — if a rectangular-mesh search stalls, search at the default
-bandwidth first and only sharpen afterwards.
+Gradient-based searches on rectangular meshes must use the kernel-CDF `RectangularRTUAdaptDensity` /
+`RectangularRTUAdaptImage` meshes (or set `over_sample_size_pixelization >= 4`): the default
+`RectangularBilinearAdaptDensity` mesh's rank-CDF likelihood is exactly piecewise-constant in the mass model at
+the default over-sampling, so its gradients are identically zero. For the RTU meshes one further setting
+matters: a sharp `bandwidth` (e.g. 0.1) gives the mesh narrow gradient support that can stall descent, whereas
+the default `bandwidth=1.0` searches on a smoother likelihood at only a small cost in final fit quality — if a
+rectangular-mesh search stalls, search at the default bandwidth first and only sharpen afterwards.
 
 Because it manages its own broad starting points, this search does not use the start-point API described below. Like
 all optimizers it returns a single best-fit lens model, not a posterior with errors, so `Nautilus` above remains the