Merge main into feature/rst-to-myst-md (port Colab tag bumps to .md)

Catches the branch up to main. The 2026.5.1.1 and 2026.5.1.4 release
commits bumped the Colab URL tag in several .rst files on main; those
files were deleted in the conversion, so the modify/delete conflicts
are resolved by keeping the deletion and porting the bump
(2026.4.13.6 → 2026.5.1.4) to the MyST .md siblings:

- docs/index.md
- docs/howtolens/chapter_1_introduction.md
- docs/howtolens/chapter_2_lens_modeling.md
- docs/howtolens/chapter_3_search_chaining.md
- docs/howtolens/chapter_4_pixelizations.md
- docs/howtolens/chapter_optional.md
- docs/overview/overview_2_new_user_guide.md

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Author: 2 people

README.rst

@@ -5,7 +5,7 @@ PyAutoLens-JAX: Open-Source Strong Lensing
     :trim:
 
 .. |colab| image:: https://colab.research.google.com/assets/colab-badge.svg
-   :target: https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.4.13.6/start_here.ipynb
+   :target: https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.5.1.4/start_here.ipynb
 
 .. |RTD| image:: https://readthedocs.org/projects/pyautolens/badge/?version=latest
     :target: https://pyautolens.readthedocs.io/en/latest/?badge=latest
@@ -46,7 +46,7 @@ PyAutoLens-JAX: Open-Source Strong Lensing
 
 `Installation Guide <https://pyautolens.readthedocs.io/en/latest/installation/overview.html>`_ |
 `readthedocs <https://pyautolens.readthedocs.io/en/latest/index.html>`_ |
-`Introduction on Colab <https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.4.13.6/start_here.ipynb>`_ |
+`Introduction on Colab <https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.5.1.4/start_here.ipynb>`_ |
 `HowToLens <https://pyautolens.readthedocs.io/en/latest/howtolens/howtolens.html>`_
 
 .. image:: https://github.com/Jammy2211/PyAutoLogo/blob/main/gifs/pyautolens.gif?raw=true
@@ -63,7 +63,7 @@ The following links are useful for new starters:
 
 - `The PyAutoLens readthedocs <https://pyautolens.readthedocs.io/en/latest>`_: which includes `an overview of PyAutoLens's core features <https://pyautolens.readthedocs.io/en/latest/overview/overview_1_start_here.html>`_, `a new user starting guide <https://pyautolens.readthedocs.io/en/latest/overview/overview_2_new_user_guide.html>`_ and `an installation guide <https://pyautolens.readthedocs.io/en/latest/installation/overview.html>`_.
 
-- `The introduction Jupyter Notebook on Google Colab <https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.4.13.6/start_here.ipynb>`_: try **PyAutoLens** in a web browser (without installation).
+- `The introduction Jupyter Notebook on Google Colab <https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.5.1.4/start_here.ipynb>`_: try **PyAutoLens** in a web browser (without installation).
 
 - `The autolens_workspace GitHub repository <https://github.com/PyAutoLabs/autolens_workspace>`_: example scripts covering every **PyAutoLens** use case.
 

autolens/__init__.py

@@ -117,6 +117,8 @@
 from .point.solver.shape_solver import ShapeSolver
 from .quantity.fit_quantity import FitQuantity
 from .quantity.model.analysis import AnalysisQuantity
+from .weak.dataset import WeakDataset
+from .weak.simulator import SimulatorShearYX
 
 from . import exc
 from . import mock as m
@@ -131,7 +133,7 @@
 
 conf.instance.register(__file__)
 
-__version__ = "2026.4.13.6"
+__version__ = "2026.5.1.4"
 
 from autoconf import check_version
 

autolens/analysis/analysis/lens.py

@@ -61,6 +61,13 @@ def __init__(
         self.cosmology = cosmology or Planck15()
         self.positions_likelihood_list = positions_likelihood_list
 
+        # Mirror the autofit Analysis fallback: if jax isn't installed,
+        # downgrade silently here too (the parent Analysis.__init__ already
+        # emitted the loud banner — no need to repeat it).
+        import importlib.util
+        if use_jax and importlib.util.find_spec("jax") is None:
+            use_jax = False
+
         self._use_jax = use_jax
 
     @property

autolens/analysis/result.py

@@ -314,12 +314,33 @@ def positions_likelihood_from(
         Outside test mode this branch is never taken — bad positions still surface as
         the original error, so production fits are not silently masked.
 
+        Skip-checks safeguard (``PYAUTO_SKIP_CHECKS``): when validation checks are
+        skipped *and* test mode is active, we return a ``PositionsLH`` built from the
+        same synthetic ``[(1.0, 0.0), (-1.0, 0.0)]`` pair (with threshold set to
+        ``minimum_threshold`` or 0.5 if unset). This avoids the expensive
+        multiple-image-position computation while still giving callers a usable
+        ``PositionsLH``, so workspace scripts that chain ``.positions`` continue to
+        work end-to-end. With skip-checks alone (no test mode) the function still
+        returns ``None`` — the production opt-out behaviour is unchanged.
+
         Returns
         -------
         The `PositionsLH` object used to apply a likelihood penalty or resample the positions.
         """
 
         if skip_checks():
+            if is_test_mode():
+                synthetic_positions = aa.Grid2DIrregular(
+                    values=[(1.0, 0.0), (-1.0, 0.0)]
+                )
+                synthetic_threshold = (
+                    minimum_threshold if minimum_threshold is not None else 0.5
+                )
+                return PositionsLH(
+                    positions=synthetic_positions,
+                    threshold=synthetic_threshold,
+                    plane_redshift=plane_redshift,
+                )
             return
 
         positions = (
@@ -420,12 +441,16 @@ def source_plane_inversion_centre_from(
                             redshift=plane_redshift
                         )
                     )
+                    # plane_indexes_with_pixelizations is a list of plane indices that
+                    # have a pixelization, in mapper order. The mapper index for a given
+                    # plane is the position of that plane index within the list, not the
+                    # element at [plane_index].
                     mapper_index = (
-                        self.max_log_likelihood_tracer.plane_indexes_with_pixelizations[
+                        self.max_log_likelihood_tracer.plane_indexes_with_pixelizations.index(
                             plane_index
-                        ]
+                        )
                     )
-                except TypeError:
+                except (TypeError, ValueError):
                     mapper_index = 0
 
                 inversion = self.max_log_likelihood_fit.inversion

autolens/weak/__init__.py

@@ -0,0 +1,2 @@
+from autolens.weak.dataset import WeakDataset
+from autolens.weak.simulator import SimulatorShearYX

autolens/weak/dataset.py

@@ -0,0 +1,102 @@
+"""
+Data structure for weak gravitational lensing observations.
+
+Weak lensing measures the small, statistical distortion of background source-galaxy shapes induced by foreground
+mass. The observable is a *shear catalogue*: a set of complex shear components ``(gamma_2, gamma_1)`` measured at
+the (y, x) sky positions of a population of background galaxies, together with a per-galaxy noise estimate
+(typically dominated by intrinsic shape noise — each galaxy has a random unlensed ellipticity that adds to its
+measured shear).
+
+``WeakDataset`` holds those three quantities together. It is the weak-lensing analogue of
+:class:`autolens.point.dataset.PointDataset` and is the input to a :class:`autolens.weak.fit.FitWeak` (added in a
+follow-up step).
+
+The shear catalogue is stored as a :class:`autogalaxy.util.shear_field.ShearYX2DIrregular` so the convention is
+the same one pinned by ``PyAutoGalaxy`` PR #366: column 0 is :math:`\\gamma_2`, column 1 is :math:`\\gamma_1`,
+and the (y, x) galaxy positions are accessible via ``shear_yx.grid``.
+"""
+from typing import List, Optional, Union
+
+import autoarray as aa
+
+from autogalaxy.util.shear_field import ShearYX2DIrregular
+
+
+class WeakDataset:
+    def __init__(
+        self,
+        shear_yx: ShearYX2DIrregular,
+        noise_map: Union[float, aa.ArrayIrregular, List[float]],
+        name: str = "",
+    ):
+        """
+        A weak-lensing shear catalogue: a ``ShearYX2DIrregular`` shear field plus a per-galaxy noise map.
+
+        Parameters
+        ----------
+        shear_yx
+            The measured (or simulated) shear at each background source-galaxy position. Shape
+            ``[total_galaxies, 2]`` with column 0 = :math:`\\gamma_2`, column 1 = :math:`\\gamma_1`. The (y, x)
+            positions of the galaxies are carried by ``shear_yx.grid``.
+        noise_map
+            The per-galaxy shear noise standard deviation (one value per galaxy). For weak lensing this is
+            dominated by intrinsic shape noise, typically in the range 0.2 - 0.4 per shear component. A scalar
+            broadcasts to a constant noise level across all galaxies.
+        name
+            Optional label, mirroring ``PointDataset.name``. Used by downstream fitting code to pair this
+            dataset with a corresponding model component when multiple datasets are fitted simultaneously.
+        """
+        self.name = name
+
+        if not isinstance(shear_yx, ShearYX2DIrregular):
+            raise TypeError(
+                "WeakDataset.shear_yx must be a ShearYX2DIrregular instance; "
+                f"got {type(shear_yx).__name__}."
+            )
+
+        self.shear_yx = shear_yx
+
+        n_galaxies = len(shear_yx)
+
+        if isinstance(noise_map, (float, int)):
+            noise_map = [float(noise_map)] * n_galaxies
+
+        if not isinstance(noise_map, aa.ArrayIrregular):
+            noise_map = aa.ArrayIrregular(values=list(noise_map))
+
+        if len(noise_map) != n_galaxies:
+            raise ValueError(
+                f"WeakDataset.noise_map has length {len(noise_map)} but shear_yx has "
+                f"{n_galaxies} entries; the two must match."
+            )
+
+        self.noise_map = noise_map
+
+    @property
+    def positions(self) -> aa.Grid2DIrregular:
+        """The (y, x) sky positions of the source galaxies the shear is measured at."""
+        return self.shear_yx.grid
+
+    @property
+    def n_galaxies(self) -> int:
+        """Number of source galaxies in the catalogue."""
+        return len(self.shear_yx)
+
+    @property
+    def info(self) -> str:
+        """A short human-readable summary of the dataset, mirroring ``PointDataset.info``."""
+        return (
+            f"name : {self.name}\n"
+            f"n_galaxies : {self.n_galaxies}\n"
+            f"shear_yx : {self.shear_yx}\n"
+            f"noise_map : {self.noise_map}\n"
+        )
+
+    def extent_from(self, buffer: float = 0.1) -> List[float]:
+        """The axis-aligned bounding box of the source-galaxy positions, padded by ``buffer`` on each side."""
+        positions = self.positions
+        y_max = max(positions[:, 0]) + buffer
+        y_min = min(positions[:, 0]) - buffer
+        x_max = max(positions[:, 1]) + buffer
+        x_min = min(positions[:, 1]) - buffer
+        return [y_min, y_max, x_min, x_max]

autolens/weak/simulator.py

@@ -0,0 +1,139 @@
+"""
+Simulate weak-lensing shear catalogues from a ``Tracer``.
+
+The shear field of a strong lens system is computed by ``Tracer.shear_yx_2d_via_hessian_from``, which differentiates
+the deflection-angle field to derive the lensing Hessian and from there the (gamma_2, gamma_1) shear at any (y, x).
+That gives a *noise-free* shear field; this module adds two extras needed for a realistic weak-lensing simulation:
+
+1. **Shape noise.** Each background source galaxy has a random unlensed ellipticity, drawn here as iid Gaussian
+   noise per shear component with standard deviation ``noise_sigma``. Realistic values are around 0.2 - 0.4.
+
+2. **Source-galaxy positions.** Either provide an explicit grid of (y, x) source positions, or let the simulator
+   draw a uniform-random distribution of ``n_galaxies`` positions inside a square arc-second extent — sufficient
+   for development work; future iterations may swap in number-density / luminosity-function-driven distributions.
+
+The output is a :class:`autolens.weak.dataset.WeakDataset`.
+"""
+from typing import Optional
+
+import numpy as np
+
+import autoarray as aa
+
+from autogalaxy.operate.lens_calc import LensCalc
+from autogalaxy.util.shear_field import ShearYX2DIrregular
+
+from autolens.weak.dataset import WeakDataset
+
+
+class SimulatorShearYX:
+    def __init__(self, noise_sigma: float = 0.3, seed: Optional[int] = None):
+        """
+        Simulator for weak-lensing shear catalogues.
+
+        Parameters
+        ----------
+        noise_sigma
+            Standard deviation of the per-component Gaussian shape noise added to each measured shear vector.
+            Values around 0.2 - 0.4 are realistic for ground-based weak-lensing surveys; ``0.0`` produces a
+            noise-free shear field, useful for unit tests.
+        seed
+            Optional seed for the random number generator. When set, both the noise and the random-position
+            draws (for ``via_tracer_random_positions_from``) are reproducible.
+        """
+        self.noise_sigma = float(noise_sigma)
+        self.seed = seed
+        self._rng = np.random.default_rng(seed)
+
+    def via_tracer_from(
+        self,
+        tracer,
+        grid: aa.Grid2DIrregular,
+        name: str = "",
+    ) -> WeakDataset:
+        """
+        Simulate a weak-lensing shear catalogue from a ``Tracer`` evaluated at the given (y, x) source positions.
+
+        Computes ``tracer.shear_yx_2d_via_hessian_from(grid=grid)`` — which goes through ``LensCalc`` under the
+        hood — and adds iid Gaussian shape noise per component with std ``self.noise_sigma``.
+
+        Parameters
+        ----------
+        tracer
+            A PyAutoLens ``Tracer`` object exposing ``shear_yx_2d_via_hessian_from``.
+        grid
+            The (y, x) source-galaxy positions where the shear is measured. Must be an ``aa.Grid2DIrregular``
+            (or convertible to one).
+        name
+            Optional label passed through to ``WeakDataset.name``.
+        """
+        if not isinstance(grid, aa.Grid2DIrregular):
+            grid = aa.Grid2DIrregular(values=grid)
+
+        true_shear = self._true_shear_yx_from(tracer=tracer, grid=grid)
+
+        if self.noise_sigma > 0.0:
+            noise = self._rng.normal(
+                loc=0.0, scale=self.noise_sigma, size=true_shear.shape
+            )
+            shear_array = np.asarray(true_shear) + noise
+        else:
+            shear_array = np.asarray(true_shear)
+
+        shear_yx = ShearYX2DIrregular(values=shear_array, grid=grid)
+
+        noise_map = aa.ArrayIrregular(
+            values=[self.noise_sigma] * len(grid)
+        )
+
+        return WeakDataset(shear_yx=shear_yx, noise_map=noise_map, name=name)
+
+    def via_tracer_random_positions_from(
+        self,
+        tracer,
+        n_galaxies: int,
+        grid_extent: float = 3.0,
+        name: str = "",
+    ) -> WeakDataset:
+        """
+        Simulate a weak-lensing shear catalogue at ``n_galaxies`` uniform-random source positions.
+
+        Galaxy positions are drawn uniformly inside a square ``[-grid_extent, +grid_extent]`` arc-second box.
+        This is the simplest sensible distribution for development purposes; production weak-lensing simulations
+        typically use a survey-specific number density / redshift distribution.
+
+        Parameters
+        ----------
+        tracer
+            A PyAutoLens ``Tracer`` object.
+        n_galaxies
+            Number of background source galaxies to simulate.
+        grid_extent
+            Half-width of the square (in arc-seconds) inside which positions are drawn.
+        name
+            Optional label passed through to ``WeakDataset.name``.
+        """
+        positions = self._rng.uniform(
+            low=-grid_extent, high=grid_extent, size=(n_galaxies, 2)
+        )
+        grid = aa.Grid2DIrregular(values=positions)
+        return self.via_tracer_from(tracer=tracer, grid=grid, name=name)
+
+    @staticmethod
+    def _true_shear_yx_from(tracer, grid: aa.Grid2DIrregular):
+        """
+        Evaluate the noise-free shear field of ``tracer`` on ``grid``.
+
+        - If the input exposes ``shear_yx_2d_via_hessian_from`` directly, use it.
+        - Else, if it exposes ``deflections_between_planes_from`` (it duck-types as a ``Tracer``), build a
+          multi-plane ``LensCalc`` via ``from_tracer``.
+        - Otherwise treat the input as a mass-like object (single ``MassProfile``, ``Galaxy``, ``Galaxies``)
+          and build a single-plane ``LensCalc`` via ``from_mass_obj``. This fallback keeps the simulator
+          usable in unit tests that don't want to spin up a full ``Tracer``.
+        """
+        method = getattr(tracer, "shear_yx_2d_via_hessian_from", None)
+        if method is not None:
+            return method(grid=grid)
+        if hasattr(tracer, "deflections_between_planes_from"):
+            return LensCalc.from_tracer(tracer).shear_yx_2d_via_hessian_from(grid=grid)
+        return LensCalc.from_mass_obj(tracer).shear_yx_2d_via_hessian_from(grid=grid)