autolens.PointSolver#

class PointSolver[source]#

Bases: AbstractSolver

Determine the image plane coordinates that are traced to be a source plane coordinate.

This is performed efficiently by iteratively subdividing the image plane into triangles and checking if the source plane coordinate is contained within the triangle. The triangles are subsampled to increase the resolution.

The solver is stateless with respect to the array module (xp); the array module is chosen per .solve() call and the initial triangle tiling is built lazily from the stored geometry primitives.

Parameters:
  • y_min (float) – The extent of the image plane used to tile the initial triangles.

  • y_max (float) – The extent of the image plane used to tile the initial triangles.

  • x_min (float) – The extent of the image plane used to tile the initial triangles.

  • x_max (float) – The extent of the image plane used to tile the initial triangles.

  • scale (float) – The pixel scale of the image plane. The initial triangles have this side length.

  • pixel_scale_precision (float) – The target pixel scale of the image grid.

  • magnification_threshold – The threshold for the magnification under which multiple images are filtered.

  • neighbor_degree (int) – The number of times recursively add neighbors for the triangles that contain the source plane coordinate.

  • use_jax (bool) – If True, .solve() defaults to xp=jnp and remove_infinities=False (the JAX-static-shape contract), and registers Tracer plus the concrete galaxy / profile classes it carries as JAX pytrees on the first call. The user wraps the call in their own @jax.jit — see the lens_calc.py workspace guide for the canonical pattern.

  • residual_threshold (Optional[float]) –

    PointSolver rejects every candidate image whose source-plane residual |beta(theta) - beta| exceeds residual_threshold * pixel_scale_precision. The default is 10.0; None disables the filter.

    This removes candidates on the centre of a zero-core mass profile (e.g. a dPIEMassSph cluster member with r_core=0, PyAutoLens#799). The deflection is discontinuous there, so a triangle around the centre traces to a triangle inscribed in a circle of the member’s Einstein radius. That triangle can contain the source at every refinement step with no root inside it. The candidate then lies within one final triangle of the centre, with a residual of order the Einstein radius (~0.04” on cluster members). The magnification filter can pass it, because in a near-critical host |mu| there is ~0.1-0.3.

    A true image traces to within its final triangle, so its residual is of order the final triangle edge times the largest singular value of the lens-equation Jacobian, which near a cusp is small. On the cluster and near-cusp fixtures of PyAutoLens#799, true images reach 3.6 times pixel_scale_precision (1.1 times near a cusp) and the core candidates at least 38 times, so 10 is the default: it keeps every true image with margin and removes every core candidate.

    The linearised (Newton) distance |A^-1 r| is deliberately not used, alone or combined with the residual. It does not detect a singular centre in general: at the centre of a steep power law (slope > 2) or a point mass, A is huge, so |A^-1 r| is about one final triangle edge even though the residual is hundreds of times the precision. (At a zero-core dPIE centre it is large, so it would work there.) Near a fold or cusp, true images also reach several triangle edges, because A is nearly singular.

    The cut scales with pixel_scale_precision. At a coarse precision it is looser than the ~0.04” core residuals: at 0.005 the margin is ~1.3x, and at 0.01 (a cut of 0.1”) core candidates survive. Lower residual_threshold or refine the precision if they matter.

    A true image whose lens-equation Jacobian has a large singular value can exceed the cut. Demagnified central images of a small-core, very elliptical cored profile reach ~11 times the precision, so they are rejected. They have |mu| of ~0.01-0.02, so at the default magnification_threshold (0.1) they are already removed. This only matters when the magnification threshold is lowered below ~0.02.

Methods

for_grid

Create a solver for a given grid.

for_limits_and_scale

Create a solver for an explicit image-plane extent.

solve

Solve for the image plane coordinates that are traced to the source plane coordinate.

solve_triangles

Solve for the image plane coordinates that are traced to the source plane coordinate.

steps

Iterate over the steps of the triangle solver algorithm.

tree_flatten

tree_unflatten

Attributes

n_steps

How many times should triangles be subdivided?

solve(tracer, source_plane_coordinate, xp=None, plane_redshift=None, remove_infinities=None)[source]#

Solve for the image plane coordinates that are traced to the source plane coordinate.

This is done by tiling the image plane with triangles and checking if the source plane coordinate is contained within the triangle. The triangles are sub-sampled to increase the resolution with only the triangles that contain the source plane coordinate and their neighbours being kept.

The means of the triangles are then filtered to keep only those with an absolute magnification above the threshold.

The positions are stored on an array of fixed shape defined by MAX_CONTAINING_SIZE. This ensures the array is static, which is important for JAX compatibility. This array typically has many entries which use the sentinel value of inf, subsequent JAX calculations incorporated. By default, these sentinel values are removed from the output, for example general use outside of JAX when simulating strong lenses.

Parameters:
  • tracer (Tracer) – The tracer that traces the image plane coordinates to the source plane.

  • source_plane_coordinate (Tuple[float, float]) – The plane coordinate to trace to the image plane, which by default in the source-plane coordinate but could be a coordinate in another plane is plane_redshift is input.

  • xp – The array module (numpy or jax.numpy) the solve runs in. AnalysisPoint passes jax.numpy when use_jax=True is set on the analysis. When None (the default), falls back to self._xp — which is jnp if the solver was constructed with use_jax=True and np otherwise. Pass explicitly to override.

  • plane_redshift (Optional[float]) – The redshift of the plane coordinate, which for multi-plane systems may not be the source-plane.

  • remove_infinities (Optional[bool]) – Whether to strip the inf sentinel rows from the output. When None (the default), defaults to True on the NumPy path and False on the JAX path. The JAX path keeps the padded static shape so the output crosses a jax.jit boundary cleanly; strip the infinities outside the jit if needed. The default follows the effective xp for this call, including an explicit override of the constructor backend. An explicit True or False takes precedence over this default.

Returns:

A Grid2DIrregular of image-plane coordinates. NumPy-backed on the default path, jax.Array-backed when use_jax=True (or xp=jnp).

Notes

Gradients (JAX path): the returned positions carry a jax.custom_jvp implicit fixed-point rule (dθ = A⁻¹ (dα + dβ) at the solved positions — the gravity.jl / Lombardi 2024 Eq. 30 mechanism), so jax.grad through a solver-chained likelihood is exact between image-count events instead of identically zero. See autolens.point.solver.implicit_diff for the differentiability contract (staircase quantization, caustic-crossing seams, near-critical divergence).

Smoke-test short-circuit (PYAUTO_SMALL_DATASETS): the triangle-tiling solve is the dominant cost in many simulator scripts and is meaningless on the downsized grids used for fast smoke tests. When PYAUTO_SMALL_DATASETS=1 is set the solver returns the fixed pair [(1.0, 0.0), (0.0, 1.0)] immediately, skipping solve_triangles entirely. The two coordinates are well separated so any downstream positions_likelihood_from / threshold calculation behaves normally. PYAUTO_SMALL_DATASETS is a smoke-test-only flag and is never set inside a jax.jit trace, so a plain numpy-backed Grid2DIrregular is safe here even when the surrounding analysis uses xp=jnp.

The short-circuit announces itself with a logger.warning the first time it fires in a process. It returns the same two coordinates for every lens model, so anything derived from them — a likelihood, a chi-squared, a position pairing — is model-independent, and a parity script that compares such a value against a pinned literal is measuring nothing. That failure mode was silent until it cost a real investigation (PyAutoLens#710), hence the warning rather than a bare return.