### Inline Overlay Logic Example

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Replace calls to helper functions for overlays with direct attribute access and inline auto-extraction logic.

```python
mask=self.mask if self.mask is not None else _auto_mask_edge(array),
lines=self.lines,
```

--------------------------------

### Install PyAutoArray with Dev Dependencies

Source: https://github.com/pyautolabs/pyautoarray/blob/main/AGENTS.md

Install PyAutoArray in editable mode with development dependencies included.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Build Masked Imaging Dataset

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Creates a masked imaging dataset by defining a circular mask, applying it to data and noise maps, and bundling them into an Imaging object. This is a common setup for astronomical data analysis.

```python
mask = aa.Mask2D.circular(shape_native=(100, 100), radius=3.0, pixel_scales=0.1)
data = aa.Array2D.ones(shape_native=(100, 100), pixel_scales=0.1).apply_mask(mask)
noise_map = aa.Array2D.full(fill_value=0.05, shape_native=(100, 100), pixel_scales=0.1).apply_mask(mask)
dataset = aa.Imaging(data=data, noise_map=noise_map).apply_mask(mask=mask)
```

--------------------------------

### Create and Use Array2D

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Shows how to create 2D arrays with pixel-scale awareness, apply masks, and perform arithmetic operations. Includes loading from and saving to FITS files, resizing, and finding brightest pixels.

```python
import autoarray as aa
import numpy as np

# Create from a 2D numpy array — no mask applied
arr = aa.Array2D.no_mask(
    values=np.random.uniform(0, 1, (50, 50)),
    pixel_scales=0.1,
)

# Apply a circular mask
mask = aa.Mask2D.circular(
    shape_native=(50, 50), radius=2.0, pixel_scales=0.1
)
arr_masked = arr.apply_mask(mask=mask)

print(arr_masked.slim.shape)    # (N,)  — only unmasked pixels
print(arr_masked.native.shape)  # (50, 50) — full 2D, masked pixels = 0

# Arithmetic operations preserve the mask
arr2 = aa.Array2D.ones(shape_native=(50, 50), pixel_scales=0.1)
result = arr_masked + arr2      # returns Array2D

# Load from FITS
arr_fits = aa.Array2D.from_fits(
    file_path="image.fits",
    hdu=0,
    pixel_scales=0.1,
)

# Save to FITS
aa.output_to_fits(array=arr_masked.native_for_fits, file_path="out.fits", overwrite=True)

# Resize / pad
resized = arr_masked.resized_from(new_shape=(60, 60))

# Find the brightest pixel within a scaled-coordinate region (y0,y1,x0,x1)
coord = arr_masked.brightest_coordinate_in_region_from(region=(-1.0, 1.0, -1.0, 1.0))
print(coord)   # e.g. (0.05, -0.15)
```

--------------------------------

### Create Imaging Dataset

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Constructs an Imaging dataset container, bundling data, noise map, and PSF. Supports masking and over-sampling for light profile grids.

```python
import autoarray as aa
import numpy as np

# Build synthetic data
data = aa.Array2D.no_mask(
    values=np.random.uniform(0, 1, (100, 100)),
    pixel_scales=0.1,
)
noise_map = aa.Array2D.full(fill_value=0.1, shape_native=(100, 100), pixel_scales=0.1)

kernel = np.zeros((11, 11)); kernel[5, 5] = 1.0
psf = aa.Convolver(kernel=aa.Array2D.no_mask(kernel, pixel_scales=0.1))

dataset = aa.Imaging(
    data=data,
    noise_map=noise_map,
    psf=psf,
    over_sample_size_lp=4,
)

# Apply a circular mask
mask = aa.Mask2D.circular(shape_native=(100, 100), radius=4.0, pixel_scales=0.1)
dataset_masked = dataset.apply_mask(mask=mask)

print(dataset_masked.data.slim.shape)       # (N,)
print(dataset_masked.grids.lp.slim.shape)   # (N, 2) — coordinate grid for light profiles
```

--------------------------------

### Create and Use Mask2D

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Demonstrates creating various 2D boolean masks with pixel-scale geometry, including fully unmasked, circular, and annular masks. Shows how to derive coordinate grids and save/load masks from FITS files.

```python
import autoarray as aa
import numpy as np

# Fully-unmasked mask (all False)
mask_full = aa.Mask2D.all_false(
    shape_native=(100, 100),
    pixel_scales=0.1,          # 0.1 arcsec/pixel
)

# Circular mask: pixels inside radius=3.0 arcsec are unmasked
mask_circ = aa.Mask2D.circular(
    shape_native=(100, 100),
    radius=3.0,
    pixel_scales=0.1,
    centre=(0.0, 0.0),
)

# Annular mask: unmasked between inner=0.5 and outer=3.0 arcsec
mask_annulus = aa.Mask2D.circular_annular(
    shape_native=(100, 100),
    inner_radius=0.5,
    outer_radius=3.0,
    pixel_scales=0.1,
)

print(mask_circ.shape_native)          # (100, 100)
print(mask_circ.pixels_in_mask)        # total number of unmasked pixels
print(mask_circ.pixel_scales)          # (0.1, 0.1)

# Derive the (y,x) coordinate grid of unmasked pixels
grid = mask_circ.derive_grid.unmasked  # Grid2D in scaled (arcsec) coords

# Save / load as FITS
aa.output_to_fits(array=mask_circ, file_path="mask.fits", overwrite=True)
mask_loaded = aa.Mask2D.from_fits(
    file_path="mask.fits",
    pixel_scales=0.1,
)
```

--------------------------------

### Reset Local Repository to Origin Main

Source: https://github.com/pyautolabs/pyautoarray/blob/main/AGENTS.md

Fetch the latest changes from the origin and reset the local branch to match origin/main, cleaning untracked files.

```bash
git fetch origin
git reset --hard origin/main
git clean -fd
```

--------------------------------

### Construct Annular and FITS Masks

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Demonstrates creating annular masks using `circular_annular` and loading masks from FITS files using `from_fits`. These methods provide flexible ways to define masked regions in astronomical data.

```python
import autoarray as aa

# Annular mask
mask_ann = aa.Mask2D.circular_annular(
    shape_native=(200, 200),
    inner_radius=0.5,
    outer_radius=5.0,
    pixel_scales=0.05,
    centre=(0.0, 0.0),
)
print(f"Unmasked pixels: {mask_ann.pixels_in_mask}")

# Border pixels (outer edge of unmasked region — used in border relocation)
border_grid = mask_ann.derive_grid.border   # Grid2D of border pixel coordinates

# Edge pixels (one pixel inside the border)
edge_grid = mask_ann.derive_grid.edge

# Load mask from FITS
mask_fits = aa.Mask2D.from_fits(
    file_path="mask.fits",
    pixel_scales=0.05,
)

# Sub-gridded (over-sampled) index arrays
slim_to_native = mask_ann.derive_indexes.native_for_slim
print(slim_to_native.shape)   # (N, 2) — [row, col] for each unmasked pixel
```

--------------------------------

### JAX Compatibility Pattern

Source: https://github.com/pyautolabs/pyautoarray/blob/main/CLAUDE.md

Use an `if xp is np:` guard to return a raw JAX array when `xp` is `jnp`, and an autoarray wrapper when `xp` is `np`. This prevents `TypeError` when returning from `jax.jit`.

```python
import jax.numpy as jnp
import numpy as np
import autoarray as aa

def convergence_2d_via_hessian_from(self, grid, xp=np):
    hessian_yy, hessian_xx = ...
    convergence = 0.5 * (hessian_yy + hessian_xx)

    if xp is np:
        return aa.ArrayIrregular(values=convergence)   # numpy: wrapped
    return convergence                                   # jax: raw jax.Array

```

--------------------------------

### Load Imaging Dataset from FITS

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Loads an Imaging dataset from FITS files, specifying paths for data, noise map, and PSF, along with pixel scales.

```python
# Load from FITS (standard workflow)
dataset_fits = aa.Imaging.from_fits(
    data_path="data.fits",
    noise_map_path="noise_map.fits",
    psf_path="psf.fits",
    pixel_scales=0.1,
)
```

--------------------------------

### Run Full PyAutoArray Test Suite

Source: https://github.com/pyautolabs/pyautoarray/blob/main/AGENTS.md

Execute the complete test suite for PyAutoArray using pytest.

```bash
python -m pytest test_autoarray/
```

--------------------------------

### Run PyAutoArray Tests with Numba and Matplotlib Caching

Source: https://github.com/pyautolabs/pyautoarray/blob/main/AGENTS.md

Run PyAutoArray tests with specified Numba and Matplotlib cache directories to manage temporary files.

```bash
NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python -m pytest test_autoarray/
```

--------------------------------

### Create Uniform Grid2D

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Instantiate a uniform Grid2D from shape and pixel scale, or from an existing mask. Supports various creation methods including bounding box and extent.

```python
import autoarray as aa

# Uniform grid from shape and pixel scale
grid = aa.Grid2D.uniform(
    shape_native=(100, 100),
    pixel_scales=0.1,
    over_sample_size=4,   # 4x4 sub-pixel grid per pixel for integration
)

# Grid from an existing mask (most common use)
mask = aa.Mask2D.circular(shape_native=(100, 100), radius=3.0, pixel_scales=0.1)
grid_masked = aa.Grid2D.from_mask(mask=mask)

print(grid_masked.slim.shape)    # (N, 2) — (y,x) for each unmasked pixel
print(grid_masked.native.shape)  # (100, 100, 2)

# Bounding box grid
grid_box = aa.Grid2D.bounding_box(
    bounding_box=[-3.0, 3.0, -3.0, 3.0],  # [y_min, y_max, x_min, x_max]
    shape_native=(60, 60),
)

# From extent tuple  (x0, x1, y0, y1)
grid_ext = aa.Grid2D.from_extent(
    extent=(-3.0, 3.0, -3.0, 3.0),
    shape_native=(60, 60),
)

# Access raw coordinates
y = grid_masked[:, 0]   # y-values of unmasked pixels
x = grid_masked[:, 1]   # x-values

# Distances from the origin
distances = grid_masked.distances_to_coordinate_from(coordinate=(0.0, 0.0))
print(distances.slim.shape)  # (N,)  — Array2D

# Blurring grid: pixels just outside the mask that contribute after PSF convolution
blurring_grid = aa.Grid2D.blurring_grid_from(
    mask=mask, kernel_shape_native=(11, 11)
)

# Radial profile projection from centre at angle 0 degrees
radial_grid = grid_masked.grid_2d_radial_projected_from(
    centre=(0.0, 0.0), angle=0.0
)  # -> Grid2DIrregular
```

--------------------------------

### FitImagingPlotter Constructor Update

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Update the FitImagingPlotter constructor to accept individual overlay arguments instead of a Visuals2D object.

```python
def __init__(self, fit, mat_plot_2d=None,
             mask=None, grid=None, positions=None, lines=None,
             residuals_symmetric_cmap=True):
```

--------------------------------

### InterferometerPlotter Constructor Update

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Update the InterferometerPlotter constructor to accept individual overlay arguments instead of Visuals objects.

```python
def __init__(self, dataset, mat_plot_1d=None, mat_plot_2d=None, lines=None):
```

--------------------------------

### Grid2DPlotter Constructor Update

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Update the Grid2DPlotter constructor to accept individual overlay arguments instead of a Visuals2D object.

```python
def __init__(self, grid, mat_plot_2d=None, lines=None, positions=None):
```

--------------------------------

### Output-Wrapping Decorators for Profile Methods

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Decorators @to_array, @transform, and @to_vector_yx automatically wrap raw array outputs from profile methods into appropriate autoarray types (Array2D, Grid2D, VectorYX2D). The output type matches the input grid type, enabling seamless switching between uniform and irregular grids.

```python
import autoarray as aa
import numpy as np


class GaussianProfile:
    def __init__(self, centre=(0.0, 0.0), sigma=1.0, intensity=1.0):
        self.centre = centre
        self.sigma = sigma
        self.intensity = intensity

    @aa.grid_dec.to_array           # outer: wraps raw output → Array2D or ArrayIrregular
    @aa.grid_dec.transform          # inner: translates/rotates grid to profile frame
    def image_2d_from(self, grid, xp=np, **kwargs):
        # grid is already shifted/rotated — access raw values with .array
        y = grid.array[:, 0]
        x = grid.array[:, 1]
        r2 = y**2 + x**2
        # Must return a raw numpy array (decorator does the wrapping)
        return self.intensity * xp.exp(-0.5 * r2 / self.sigma**2)


mask = aa.Mask2D.circular(shape_native=(50, 50), radius=2.5, pixel_scales=0.1)
grid = aa.Grid2D.from_mask(mask=mask)

profile = GaussianProfile(centre=(0.1, -0.2), sigma=0.5, intensity=2.0)

# With a uniform Grid2D → returns Array2D
image = profile.image_2d_from(grid=grid)
print(type(image))           # <class 'autoarray.structures.arrays.uniform_2d.Array2D'>
print(image.slim.shape)      # (N,)

# With an irregular grid → returns ArrayIrregular
grid_irr = aa.Grid2DIrregular(values=[(0.0, 0.0), (1.0, 0.5)])
image_irr = profile.image_2d_from(grid=grid_irr)
print(type(image_irr))       # <class 'autoarray.structures.arrays.irregular.ArrayIrregular'>
```

--------------------------------

### Run PyAutoArray Tests with Captured Output

Source: https://github.com/pyautolabs/pyautoarray/blob/main/AGENTS.md

Execute tests for a specific file, showing captured output during test execution.

```bash
python -m pytest test_autoarray/structures/test_arrays.py -s
```

--------------------------------

### Format PyAutoArray Code with Black

Source: https://github.com/pyautolabs/pyautoarray/blob/main/AGENTS.md

Format the PyAutoArray codebase using the Black code formatter.

```bash
black autoarray/
```

--------------------------------

### Create and Manipulate 2D Vector Fields

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Illustrates the creation and manipulation of `VectorYX2D` objects, which represent 2D vector fields on a grid. It shows construction from raw data, shape properties, and basic arithmetic operations.

```python
import autoarray as aa
import numpy as np

mask = aa.Mask2D.circular(shape_native=(50, 50), radius=2.0, pixel_scales=0.1)
grid = aa.Grid2D.from_mask(mask=mask)

# Construct from raw slim array of shape (N, 2)
N = mask.pixels_in_mask
raw_vectors = np.column_stack([np.ones(N) * 0.5, np.zeros(N)])
vectors = aa.VectorYX2D(values=raw_vectors, mask=mask)

print(vectors.slim.shape)    # (N, 2)
print(vectors.native.shape)  # (50, 50, 2)

# Arithmetic
scaled = vectors * 2.0       # returns VectorYX2D
norms = np.sqrt(vectors[:, 0]**2 + vectors[:, 1]**2)  # raw numpy

# Irregular variant for non-uniform grids
irr_vectors = aa.VectorYX2DIrregular(values=raw_vectors[:10])
print(irr_vectors.shape)     # (10, 2)
```

--------------------------------

### Simulate Imaging Data

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Generates a synthetic Imaging dataset by convolving a model image with a PSF, adding background sky, and Poisson noise. Noise and PSF convolution can be toggled.

```python
import autoarray as aa
import numpy as np

# PSF kernel
kernel = np.zeros((11, 11)); kernel[5, 5] = 1.0
from scipy.ndimage import gaussian_filter
kernel = gaussian_filter(kernel, sigma=1.0)

psf = aa.Convolver(kernel=aa.Array2D.no_mask(kernel, pixel_scales=0.1))

simulator = aa.SimulatorImaging(
    exposure_time=1000.0,
    background_sky_level=0.05,
    psf=psf,
    add_poisson_noise_to_data=True,
    noise_seed=42,
)

# Noiseless model image
model_image = aa.Array2D.no_mask(
    values=np.random.uniform(0, 0.5, (100, 100)),
    pixel_scales=0.1,
)

# Produce a simulated Imaging dataset
dataset = simulator.via_image_from(image=model_image)

print(dataset.data.shape_native)    # (100, 100)
print(dataset.noise_map.slim.min()) # positive noise values
```

--------------------------------

### ImagingPlotter Constructor Update

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Update the ImagingPlotter constructor to accept individual overlay arguments instead of a Visuals2D object.

```python
def __init__(self, dataset, mat_plot_2d=None,
             mask=None, grid=None, positions=None, lines=None):
```

--------------------------------

### Array2DPlotter Constructor Update

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Update the Array2DPlotter constructor to accept individual overlay arguments instead of a Visuals2D object.

```python
def __init__(self, array, mat_plot_2d=None,
             mask=None, origin=None, border=None, grid=None,
             positions=None, lines=None, vectors=None,
             patches=None, fill_region=None, array_overlay=None):
```

--------------------------------

### YX1DPlotter Constructor Update

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Update the YX1DPlotter constructor to accept individual overlay arguments instead of a Visuals1D object.

```python
def __init__(self, y, x=None, mat_plot_1d=None,
             shaded_region=None, vertical_line=None, points=None, ...):
```

--------------------------------

### Create a Feature Branch

Source: https://github.com/pyautolabs/pyautoarray/blob/main/CONTRIBUTING.md

Before making any changes, create a new branch for your feature or bug fix. This isolates your work from the main codebase.

```bash
git checkout -b feature/name-of-your-branch
```

--------------------------------

### Capture All Plots to Output Directory

Source: https://github.com/pyautolabs/pyautoarray/blob/main/CLAUDE.md

Sets the PYAUTO_OUTPUT_MODE environment variable to 1, which captures all generated figures into numbered PNG files in the ./output_mode/<script_name>/ directory. This bypasses normal save paths and is useful for visual inspection.

```bash
PYAUTO_OUTPUT_MODE=1 python scripts/my_script.py
```

--------------------------------

### InversionPlotter Constructor Update

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Update the InversionPlotter constructor to accept individual overlay arguments instead of a Visuals2D object.

```python
def __init__(self, inversion, mat_plot_2d=None,
             lines=None, grid=None, positions=None,
             residuals_symmetric_cmap=True):
```

--------------------------------

### Run Specific PyAutoArray Test File

Source: https://github.com/pyautolabs/pyautoarray/blob/main/AGENTS.md

Execute tests for a specific file within the PyAutoArray test suite.

```bash
python -m pytest test_autoarray/structures/test_arrays.py
```

--------------------------------

### Create Rectangular Uniform Mesh and Regularization

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Defines a rectangular uniform mesh for pixelization and a constant regularization scheme to smooth the reconstruction. These are then bundled into a Pixelization object.

```python
mesh = aa.mesh.RectangularUniform(shape=(50, 50), pixel_scales_ratio=1.0)
regularization = aa.reg.Constant(coefficient=1.0)
pixelization = aa.Pixelization(mesh=mesh, regularization=regularization)
```

--------------------------------

### MapperPlotter Constructor Update

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Update the MapperPlotter constructor to accept individual overlay arguments instead of a Visuals2D object.

```python
def __init__(self, mapper, mat_plot_2d=None,
             lines=None, grid=None, positions=None):
```

--------------------------------

### Create No-Blur Convolver

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Initializes a Convolver object that performs no blurring, effectively acting as an identity operation for convolution.

```python
# No-blur (identity) convolver
psf_none = aa.Convolver.no_blur(pixel_scales=0.1)
```

--------------------------------

### Build Gaussian PSF Kernel for Convolution

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Constructs a Gaussian Point Spread Function (PSF) kernel using scipy.ndimage.gaussian_filter for use with the Convolver class.

```python
import autoarray as aa
import numpy as np
from scipy.ndimage import gaussian_filter

# Build a Gaussian PSF kernel
kernel_array = np.zeros((21, 21))
kernel_array[10, 10] = 1.0
kernel_array = gaussian_filter(kernel_array, sigma=1.5)

psf = aa.Convolver(kernel=aa.Array2D.no_mask(kernel_array, pixel_scales=0.1))
```

--------------------------------

### Fit Imaging Dataset

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Calculates goodness-of-fit metrics like residuals, chi-squared, and log-likelihood for a model image against a masked Imaging dataset. Requires a custom subclass to provide model data.

```python
import autoarray as aa
import numpy as np


class SimpleModel:
    """Minimal stand-in for a galaxy / lens model."""

    def __init__(self, image):
        self._image = image

    def image_2d_from(self, grid, xp=np, **kwargs):
        return self._image


# Build a masked dataset
data = aa.Array2D.no_mask(np.random.normal(1.0, 0.1, (50, 50)), pixel_scales=0.1)
noise_map = aa.Array2D.full(fill_value=0.1, shape_native=(50, 50), pixel_scales=0.1)
mask = aa.Mask2D.circular(shape_native=(50, 50), radius=2.0, pixel_scales=0.1)

dataset = aa.Imaging(data=data, noise_map=noise_map).apply_mask(mask=mask)

# FitImaging subclass example (model_data must be provided by subclass)
class MyFit(aa.FitImaging):
    def __init__(self, dataset, model_image):
        super().__init__(dataset=dataset)
        self._model_image = model_image

    @property
    def model_data(self):
        return self._model_image


model_image = dataset.data * 1.05   # slightly offset model
fit = MyFit(dataset=dataset, model_image=model_image)

print(fit.residual_map.slim.shape)         # (N,)
print(fit.normalized_residual_map.slim[:5])
print(fit.chi_squared_map.slim[:5])
print(f"chi_squared       = {fit.chi_squared:.4f}")
print(f"noise_norm        = {fit.noise_normalization:.4f}")
print(f"log_likelihood    = {fit.log_likelihood:.4f}")
print(f"signal_to_noise   = {fit.signal_to_noise_map.slim.mean():.4f}")
```

--------------------------------

### Run Pytest Suite

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Execute the full test suite for PyAutoArray to identify and fix any failures introduced by the plotting refactoring. This command runs pytest in quiet mode with short traceback information.

```bash
python -m pytest test_autoarray/ -q --tb=short
```

--------------------------------

### Create Irregular Grid2DIrregular

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Instantiate an irregular Grid2DIrregular from a list of (y,x) pairs or separate y and x 1D arrays. Supports arithmetic operations.

```python
import autoarray as aa
import numpy as np

# From a list of (y,x) pairs
grid_irr = aa.Grid2DIrregular(values=[(1.0, 2.0), (-0.5, 0.3), (0.0, -1.0)])

# From separate y and x 1D arrays
grid_irr2 = aa.Grid2DIrregular.from_yx_1d(
    y=np.array([0.0, 1.0, 2.0]),
    x=np.array([0.5, -0.5, 1.0]),
)

print(grid_irr.shape)   # (3, 2)
print(grid_irr[:, 0])   # y values
print(grid_irr[:, 1])   # x values

# Arithmetic is supported — result is also Grid2DIrregular
shifted = grid_irr - np.array([0.1, 0.1])
```

--------------------------------

### Mask2D.circular_annular / Mask2D.from_fits

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Factory methods for constructing 2D masks, including annular, from FITS files, and elliptical forms. These masks can derive grids, border pixels, blurring masks, and zoom regions.

```APIDOC
## Mask2D.circular_annular / Mask2D.from_fits 

### Description
Additional factory methods for building real-world masks: annular (ring-shaped), from existing FITS boolean images, and elliptical forms. All masks share the same derive API for grids, border pixels, blurring masks, and zoom regions.

### Method
Factory methods

### Parameters
#### circular_annular
- **shape_native** (tuple) - The native shape of the mask (rows, columns).
- **inner_radius** (float) - The inner radius of the annular mask.
- **outer_radius** (float) - The outer radius of the annular mask.
- **pixel_scales** (float or tuple) - The pixel scales of the mask.
- **centre** (tuple) - The center of the mask (y, x).

#### from_fits
- **file_path** (str) - The path to the FITS file containing the mask.
- **pixel_scales** (float or tuple) - The pixel scales of the mask.

### Request Example
```python
import autoarray as aa

# Annular mask
mask_ann = aa.Mask2D.circular_annular(
    shape_native=(200, 200),
    inner_radius=0.5,
    outer_radius=5.0,
    pixel_scales=0.05,
    centre=(0.0, 0.0),
)

# Load mask from FITS
mask_fits = aa.Mask2D.from_fits(
    file_path="mask.fits",
    pixel_scales=0.05,
)
```

### Response
- **Mask2D** - A Mask2D object representing the constructed mask.

### Derived Quantities
- **derive_grid.border**: Grid2D of border pixel coordinates.
- **derive_grid.edge**: Grid2D of edge pixel coordinates.
- **derive_indexes.native_for_slim**: Index arrays mapping slim to native coordinates.
```

--------------------------------

### Decorator Stacking Order

Source: https://github.com/pyautolabs/pyautoarray/blob/main/CLAUDE.md

Decorators are applied bottom-up, with `transform` typically innermost and `to_array` outermost for mass/light profile methods.

```python
@aa.grid_dec.to_array        # outermost: wraps output
@aa.grid_dec.transform       # innermost: transforms grid input
def convergence_2d_from(self, grid, xp=np, **kwargs):
    ...

```

--------------------------------

### Convolve Array2D with PSF

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Convolves an Array2D with a Point Spread Function (PSF). The input image can be masked. The output is a 1D slim Array2D.

```python
image = aa.Array2D.no_mask(
    values=np.random.uniform(0, 1, (50, 50)),
    pixel_scales=0.1,
)
mask = aa.Mask2D.circular(shape_native=(50, 50), radius=2.5, pixel_scales=0.1)
image_masked = image.apply_mask(mask=mask)

blurred = psf.convolve(image=image_masked.slim)  # returns 1D slim Array2D
```

--------------------------------

### Access Raw Array Data

Source: https://github.com/pyautolabs/pyautoarray/blob/main/CLAUDE.md

Demonstrates how to access the underlying raw NumPy or JAX array from an autoarray object using the `.array` property or the internal `._array` attribute.

```python
arr = aa.ArrayIrregular(values=[1.0, 2.0])
arr.array        # raw numpy array
arr._array       # same, internal attribute
```

--------------------------------

### Accessing Grid Coordinates

Source: https://github.com/pyautolabs/pyautoarray/blob/main/CLAUDE.md

Inside a decorated function, access the raw underlying array using `.array` or direct slicing. This works for both NumPy and JAX backends.

```python
# Correct — works for both numpy and jax backends
y = grid.array[:, 0]
x = grid.array[:, 1]

# Also correct for simple slicing (returns raw array via __getitem__)
y = grid[:, 0]
x = grid[:, 1]

```

--------------------------------

### Using @aa.grid_dec.to_array Decorator

Source: https://github.com/pyautolabs/pyautoarray/blob/main/CLAUDE.md

This decorator wraps a function's raw array output into an autoarray object. Ensure the function returns a raw array, as the decorator handles the wrapping.

```python
import numpy as np
import autoarray as aa

@aa.grid_dec.to_array
def convergence_2d_from(self, grid, xp=np, **kwargs):
    # grid is Grid2D or Grid2DIrregular — access raw values via grid.array[:,0]
    y = grid.array[:, 0]
    x = grid.array[:, 1]
    return xp.sqrt(y**2 + x**2)   # return raw array; decorator wraps it

```

--------------------------------

### Auto Mask Edge Helper Function

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

A module-level helper function to derive edge-pixel coordinates from an array's mask, returning None if no mask is present or applicable.

```python
def _auto_mask_edge(array):
    """Return edge-pixel (y,x) coords from array.mask, or None."""
    try:
        if not array.mask.is_all_false:
            return np.array(array.mask.derive_grid.edge.array)
    except AttributeError:
        pass
    return None
```

--------------------------------

### Normalize PSF

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Calculates the normalized Point Spread Function (PSF), where the sum of its array values is approximately 1.0.

```python
# Normalized PSF (sum to 1)
psf_norm = psf.normalized
print(psf_norm.array.sum())   # ~1.0
```

--------------------------------

### InversionPlotter Subplot Mappings Mutation Removal

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Remove the mutation of `self.visuals_2d.indexes` in `InversionPlotter.subplot_mappings` by storing and passing the indexes attribute directly.

```python
self.visuals_2d.indexes = indexes
```

--------------------------------

### VectorYX2D

Source: https://context7.com/pyautolabs/pyautoarray/llms.txt

Represents a uniform 2D array of (y,x) vector components, one per unmasked pixel. Used for deflection angles, velocity fields, and other vector quantities on a Grid2D.

```APIDOC
## VectorYX2D 

### Description
A uniform 2D array of (y,x) vector components, one per unmasked pixel. Used for deflection angles, velocity fields, and any other vector quantity computed on a `Grid2D`. Behaves identically to `Array2D` in arithmetic but stores 2-component values.

### Method
Constructor

### Parameters
- **values** (numpy.ndarray) - Raw array of shape (N, 2) containing vector components for unmasked pixels.
- **mask** (Mask2D) - The mask associated with the vector field.

### Request Example
```python
import autoarray as aa
import numpy as np

mask = aa.Mask2D.circular(shape_native=(50, 50), radius=2.0, pixel_scales=0.1)
grid = aa.Grid2D.from_mask(mask=mask)

# Construct from raw slim array of shape (N, 2)
N = mask.pixels_in_mask
raw_vectors = np.column_stack([np.ones(N) * 0.5, np.zeros(N)])
vectors = aa.VectorYX2D(values=raw_vectors, mask=mask)
```

### Response
- **VectorYX2D** - A VectorYX2D object representing the 2D vector field.

### Attributes
- **slim**: numpy.ndarray of shape (N, 2) representing vector components for unmasked pixels.
- **native**: numpy.ndarray of shape (rows, columns, 2) representing vector components on the native grid.
```

--------------------------------

### InversionPlotter Subplot Mutation Removal

Source: https://github.com/pyautolabs/pyautoarray/blob/main/PLAN.md

Remove the direct mutation of `self.visuals_2d` in `InversionPlotter.subplot_of_mapper` by passing mesh_grid directly to the relevant plotting call.

```python
self.visuals_2d += Visuals2D(mesh_grid=mapper.image_plane_mesh_grid)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.