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

@@ -61,7 +61,7 @@ AUTO-GENERATED by PyAutoHands — do not edit by hand; regenerate with generate.
   - Contents: Advantages & Disadvantages, Positive Only Solver, Dataset & Mask, Mesh Shape, Pixelization, Fit, Mask Extra Galaxies, Linear Objects / Grids / Reconstruction
 - [Pixelization: Galaxy Reconstruction](scripts/imaging/features/pixelization/galaxy_reconstruction.py): A common pixelization use-case is to reconstruct the irregular component of a galaxy's surface brightness on a pixelization mesh, and then export that reconstruction to perform scientific analysis.
   - Contents: Model Fit, Dataset Auto-Simulation, Reconstruction CSV
-- [__Log Likelihood Function: Pixelization__](scripts/imaging/features/pixelization/likelihood_function.py): This script provides a step-by-step guide of the **PyAutoGalaxy** `log_likelihood_function` which is used to fit `Imaging` data with a pixelization (specifically a `RectangularAdaptDensity` mesh and `Constant` regularization scheme).
+- [__Log Likelihood Function: Pixelization__](scripts/imaging/features/pixelization/likelihood_function.py): This script provides a step-by-step guide of the **PyAutoGalaxy** `log_likelihood_function` which is used to fit `Imaging` data with a pixelization (specifically a `RectangularBilinearAdaptDensity` mesh and `Constant` regularization scheme).
   - Contents: Mesh Shape, Dataset, Dataset Auto-Simulation, Mask, Over Sampling, Masked Image Grid, Galaxy, Galaxy Pixelization and Regularization, Interpolation, Mapper, Over Sampling, Alternative Meshes, Mapping Matrix, Blurred Mapping Matrix ($f$), Data Vector (D), Curvature Matrix (F), Regularization Matrix (H), F + Lamdba H, Galaxy Reconstruction (s), Image Reconstruction, Likelihood Function, Chi Squared, Regularization Term, Complexity Terms, Noise Normalization Term, Calculate The Log Likelihood, Fit, Galaxy Modeling, Log Likelihood Function: Pixelization With Light Profile, Wrap Up
 - [Features: Pixelization Modeling](scripts/imaging/features/pixelization/modeling.py): This is the canonical example of when (and why) you should reach for a pixelization in **PyAutoGalaxy**.
   - Contents: Advantages & Disadvantages, Positive Only Solver, Dataset & Mask, Pixelization, Model, Search & Analysis, Run Time, Model-Fit, Result, Chaining, Result (Advanced), Wrap Up

scripts/imaging/features/linear_light_profiles/modeling.py

@@ -324,7 +324,7 @@
    many light profiles combined in a `Basis` (e.g. `lp_basis.Basis`).
 
  - `Mapper`: The linear object used by a `Pixelization` to reconstruct data via an `Inversion`. The `Mapper`
-   is specific to the `Pixelization`'s `Mesh` (e.g. a `RectangularMapper` is used for a `RectangularAdaptDensity`
+   is specific to the `Pixelization`'s `Mesh` (e.g. a `RectangularMapper` is used for a `RectangularBilinearAdaptDensity`
    mesh).
 
 In this example, the model uses one linear `Sersic` for the galaxy's bulge and one linear `Exponential` for

scripts/imaging/features/pixelization/README.md

@@ -18,6 +18,16 @@ the pixelization absorbs whatever the Sersic cannot describe on a flexible pixel
 - `galaxy_reconstruction`: How to export the pixelized galaxy reconstruction to a .csv file which can be loaded to analyse the reconstruction without PyAutoGalaxy.
 - `plot`: How to plot pixelized galaxy reconstructions, mappers and mesh grids.
 
+# Rectangular Mesh Variants
+
+The default adaptive rectangular mesh is `RectangularBilinearAdaptDensity` (with `RectangularBilinearAdaptImage`
+its adapt-image counterpart): it warps the grid via the empirical rank CDF of the traced points — no extra
+parameters and the fastest rectangular mesh on CPUs. The advanced `RectangularRTUAdaptDensity` /
+`RectangularRTUAdaptImage` meshes use a smooth kernel-density CDF instead — the ray-guided transformed uniform
+(RTU) grid formulation of Enzi et al. (2026), https://arxiv.org/abs/2606.30620, which should be cited when using
+them. Use RTU on GPUs, for gradient-based (JAX) samplers (the Bilinear likelihood has zero gradients at the
+default `over_sample_size_pixelization=1` — set it >= 4 or use RTU), and for interferometer gradient fitting.
+
 # Results
 
 These scripts only give a brief overview of how to analyse and interpret the results of a pixelization fit.

scripts/imaging/features/pixelization/fit.py

@@ -187,7 +187,7 @@
 of the noise in the data and an unrealistically complex and structured solution. Regularization smooths the
 reconstruction by penalizing solutions where neighboring pixels have large flux differences.
 """
-mesh = ag.mesh.RectangularAdaptDensity(shape=mesh_shape)
+mesh = ag.mesh.RectangularBilinearAdaptDensity(shape=mesh_shape)
 regularization = ag.reg.Constant(coefficient=1.0)
 
 pixelization = ag.Pixelization(mesh=mesh, regularization=regularization)
@@ -320,7 +320,7 @@
  (e.g. `lp_linear.Sersic`) or many light profiles combined in a `Basis` (e.g. `lp_basis.Basis`).
 
 - `Mapper`: The linear object used by a `Pixelization` to reconstruct data via an `Inversion`, where the `Mapper`
-is specific to the `Pixelization`'s `Mesh` (e.g. a `RectangularMapper` is used for a `RectangularAdaptDensity` mesh).
+is specific to the `Pixelization`'s `Mesh` (e.g. a `RectangularMapper` is used for a `RectangularBilinearAdaptDensity` mesh).
 
 In this example, the bulge is a non-linear `lp.Sersic` so it does not enter the `Inversion`. The only linear object
 used to fit the data is therefore the pixelization `Mapper`, and `linear_obj_list` contains just one entry:

scripts/imaging/features/pixelization/galaxy_reconstruction.py

@@ -81,7 +81,7 @@
 
 pixelization = af.Model(
     ag.Pixelization,
-    mesh=ag.mesh.RectangularAdaptDensity(shape=mesh_shape),
+    mesh=ag.mesh.RectangularBilinearAdaptDensity(shape=mesh_shape),
     regularization=ag.reg.MaternKernel,
 )
 

scripts/imaging/features/pixelization/likelihood_function.py

@@ -2,7 +2,7 @@
 __Log Likelihood Function: Pixelization__
 
 This script provides a step-by-step guide of the **PyAutoGalaxy** `log_likelihood_function` which is used to fit
-`Imaging` data with a pixelization (specifically a `RectangularAdaptDensity` mesh and `Constant` regularization
+`Imaging` data with a pixelization (specifically a `RectangularBilinearAdaptDensity` mesh and `Constant` regularization
 scheme).
 
 The dataset is the `clumpy` galaxy used throughout the pixelization package — a smooth central bulge plus
@@ -183,7 +183,7 @@
 to reconstruct its star forming clumps.
 """
 pixelization = ag.Pixelization(
-    mesh=ag.mesh.RectangularAdaptDensity(shape=(30, 30)),
+    mesh=ag.mesh.RectangularBilinearAdaptDensity(shape=(30, 30)),
     regularization=ag.reg.Constant(coefficient=1.0),
 )
 
@@ -192,7 +192,7 @@
 """
 __Galaxy Pixelization and Regularization__
 
-The galaxy is reconstructed using a pixel-grid, in this example a `RectangularAdaptDensity` mesh, which accounts for
+The galaxy is reconstructed using a pixel-grid, in this example a `RectangularBilinearAdaptDensity` mesh, which accounts for
 irregularities and asymmetries in the galaxy's surface brightness — exactly the kind of clumpy structure visible
 in this dataset.
 
@@ -333,14 +333,24 @@
 We can briefly consider how this step differs for other mesh types. Above, we simply overlaid a uniform rectangular
 grid to define the reconstruction pixel centres and then mapped image pixels to these reconstruction pixels.
 
-The `RectangularAdaptDensity` mesh pretty much works exactly the same, its just that a calculation (which we don't
+The `RectangularBilinearAdaptDensity` mesh pretty much works exactly the same, its just that a calculation (which we don't
 describe here) works out how to make a grid of rectangular pixels that adapt to the data density and thus
 vary in size. 
 
-There is also a `RectangularAdaptImage` mesh which uses the image of the galaxy to adapt
+There is also a `RectangularBilinearAdaptImage` mesh which uses the image of the galaxy to adapt
 the rectangular pixel sizes. This often puts even smaller pixels in the brightest regions of the galaxy,
 even if it lies offset or away from the caustic.
 
+The adaptive rectangular meshes come in two variants which differ only in the transform used to warp the
+uniform grid: the default `RectangularBilinear` meshes use the empirical rank CDF of the traced points (a sort
+and a cumulative sum — no extra parameters, fastest on CPUs), whereas the advanced `RectangularRTU` meshes use
+a smooth kernel-density CDF — the ray-guided transformed uniform (RTU) grid formulation of Enzi et al. (2026),
+https://arxiv.org/abs/2606.30620, which should be cited when using those meshes (the paper pairs the RTU grid
+with a Gaussian-process source prior, whereas these examples use PyAutoGalaxy's own regularization schemes such
+as `reg.Constant` / `reg.Adapt`). The RTU meshes are recommended on GPUs and for gradient-based (JAX) samplers:
+the Bilinear likelihood is exactly piecewise-constant at the default `over_sample_size_pixelization=1` (zero
+gradients) — gradient users set `over_sample_size_pixelization >= 4` or use RTU.
+
 There is also a `Delaunay` mesh which uses a Delaunay triangulation to define an irregular grid of reconstruction pixels.
 This is described fully in the `delaunay` example including a likelihood function guide.
 

scripts/imaging/features/pixelization/modeling.py

@@ -10,7 +10,7 @@
  - **Asymmetric clumpy star formation** spread irregularly across the galaxy, which no parametric profile (or even a
    combination of profiles) can fit cleanly.
 
-We therefore use a hybrid model: a linear `Sersic` for the bulge, and a pixelization (with a `RectangularAdaptDensity`
+We therefore use a hybrid model: a linear `Sersic` for the bulge, and a pixelization (with a `RectangularBilinearAdaptDensity`
 mesh and `GaussianKernel` regularization scheme) for the clumpy component. The Sersic captures the smooth bulge with
 just a handful of parameters; the pixelization reconstructs whatever the Sersic cannot fit on a flexible pixel grid.
 
@@ -128,7 +128,7 @@
 
  - The galaxy's smooth central bulge is fit with a linear `Sersic` light profile.
  - The galaxy's asymmetric clumpy star formation is reconstructed using a pixelization with a
-   `RectangularAdaptDensity` mesh and `GaussianKernel` regularization scheme.
+   `RectangularBilinearAdaptDensity` mesh and `GaussianKernel` regularization scheme.
 
 __Start Here Notebook__
 
@@ -235,7 +235,7 @@
    `intensity` is solved for via the same linear inversion that solves for the pixelization reconstruction, removing
    one non-linear parameter and avoiding the bulge/pixelization brightness degeneracy.
 
- - The galaxy's asymmetric **clumpy star formation** is reconstructed with a 28 x 28 `RectangularAdaptDensity` mesh
+ - The galaxy's asymmetric **clumpy star formation** is reconstructed with a 28 x 28 `RectangularBilinearAdaptDensity` mesh
    [0 parameters], regularized with a `GaussianKernel` scheme that smooths the reconstruction [2 parameters].
 
 The number of free parameters and therefore the dimensionality of non-linear parameter space is N=8.
@@ -246,7 +246,7 @@
 """
 pixelization = af.Model(
     ag.Pixelization,
-    mesh=ag.mesh.RectangularAdaptDensity(shape=mesh_shape),
+    mesh=ag.mesh.RectangularBilinearAdaptDensity(shape=mesh_shape),
     regularization=ag.reg.GaussianKernel,
 )
 
@@ -366,7 +366,7 @@
 """
 pixelization = af.Model(
     ag.Pixelization,
-    mesh=ag.mesh.RectangularAdaptDensity(shape=mesh_shape),
+    mesh=ag.mesh.RectangularBilinearAdaptDensity(shape=mesh_shape),
     regularization=ag.reg.GaussianKernel,
 )
 

scripts/imaging/features/pixelization/plot.py

@@ -70,7 +70,7 @@
 dataset = dataset.apply_mask(mask=mask)
 
 pixelization = ag.Pixelization(
-    mesh=ag.mesh.RectangularAdaptDensity(shape=(25, 25)),
+    mesh=ag.mesh.RectangularBilinearAdaptDensity(shape=(25, 25)),
     regularization=ag.reg.Constant(coefficient=1.0),
 )
 

scripts/interferometer/features/linear_light_profiles/modeling.py

@@ -365,7 +365,7 @@
    many light profiles combined in a `Basis` (e.g. `lp_basis.Basis`).
 
  - `Mapper`: The linear object used by a `Pixelization` to reconstruct data via an `Inversion`. The `Mapper`
-   is specific to the `Pixelization`'s `Mesh` (e.g. a `RectangularMapper` is used for a `RectangularAdaptDensity`
+   is specific to the `Pixelization`'s `Mesh` (e.g. a `RectangularMapper` is used for a `RectangularBilinearAdaptDensity`
    mesh).
 
 In this example, the model uses one linear `Sersic` for the galaxy's bulge and one linear `Exponential` for

scripts/interferometer/features/pixelization/likelihood_function.py

@@ -327,7 +327,7 @@
 describe here) works out how to make a grid of rectangular pixels that adapt to the data density and thus
 vary in size.
 
-There is also a `RectangularAdaptImage` mesh which uses the image of the galaxy to adapt
+There is also a `RectangularBilinearAdaptImage` mesh which uses the image of the galaxy to adapt
 the rectangular pixel sizes. This often puts even smaller pixels in the brightest regions of the galaxy,
 even if it lies offset or away from the caustic.
 

scripts/multi_dataset/features/pixelization/modeling.py

@@ -144,7 +144,7 @@
 We compose our galaxy model using `Model` objects, which represent the galaxies we fit to our data. In this 
 example we fit a galaxy model where:
 
- - The galaxy's light uses a `RectangularAdaptDensity` meshwhose resolution is free to vary [2 parameters]. 
+ - The galaxy's light uses a `RectangularBilinearAdaptDensity` meshwhose resolution is free to vary [2 parameters]. 
 
  - This pixelization is regularized using a `Constant` scheme which smooths every pixel 
  equally, where its `regularization_coefficient` varies across the datasets [2 parameter]. 
@@ -153,7 +153,7 @@
 """
 pixelization = af.Model(
     ag.Pixelization,
-    mesh=af.Model(ag.mesh.RectangularAdaptDensity, shape=mesh_shape),
+    mesh=af.Model(ag.mesh.RectangularBilinearAdaptDensity, shape=mesh_shape),
     regularization=ag.reg.Constant,
 )