refactor: simplify decorator type-dispatch system #276

Affected Repositories

• PyAutoArray (primary)
• PyAutoGalaxy (consumer — decorator usage, rename)
• PyAutoLens (consumer — decorator usage, rename)

Work Classification

Library

Branch Survey

Suggested branch: feature/data-typing-simplify
Worktree root: ~/Code/PyAutoLabs-wt/data-typing-simplify/

Implementation Steps

Phase 1 — Tests (zero-risk)

1. Expand test_autoarray/test_decorators.py with tests for:
   • @to_array with Grid2D input → asserts Array2D output with correct mask
   • @to_array with Grid2DIrregular input → asserts ArrayIrregular output
   • @to_array with raw np.ndarray → asserts np.ndarray passthrough
   • @to_vector_yx with Grid2D → asserts VectorYX2D
   • @to_vector_yx with Grid2DIrregular → asserts VectorYX2DIrregular
   • @to_grid with Grid2D → asserts Grid2D with over-sampling metadata preserved
   • @to_grid with Grid2DIrregular → asserts Grid2DIrregular
   • @transform — coordinate frame transformation applied and reversed
   • List return handling for all decorators
   • JAX array passthrough (if jax available)

Phase 2 — Targeted cleanup (low risk)

2. Remove Grid1D isinstance branch and via_grid_1d() from all three makers (to_array.py, to_grid.py, to_vector_yx.py) and the 1D projection logic from abstract.py
3. Extract list-return handling from each maker into a shared helper in abstract.py
4. Move over-sampling metadata try/except from GridMaker.via_grid_2d() into cleaner getattr calls or into Grid2D's own construction
5. Rename grid_dec → decorators in autoarray/__init__.py and update all aa.grid_dec. references in PyAutoGalaxy and PyAutoLens

Phase 3 — Registry consolidation (follow-up, moderate risk)

6. Replace the three Maker classes with a single generic wrapper + lookup table:

   {(Grid2D, "array"): Array2D, (Grid2DIrregular, "array"): ArrayIrregular, ...}
   

7. Keep external API (to_array, to_vector_yx, to_grid) as thin wrappers so downstream code doesn't change
8. Run full test suites across PyAutoArray, PyAutoGalaxy, PyAutoLens

Key Files

• autoarray/structures/decorators/abstract.py — base maker class, isinstance routing
• autoarray/structures/decorators/to_array.py — ArrayMaker
• autoarray/structures/decorators/to_grid.py — GridMaker (over-sampling complexity)
• autoarray/structures/decorators/to_vector_yx.py — VectorYXMaker
• autoarray/structures/decorators/transform.py — coordinate frame decorator
• test_autoarray/test_decorators.py — currently near-empty (11 lines)
• autoarray/__init__.py — exports grid_dec

The different data structures in PyAutoArray are quite confusing, in some ways:

• Array2D
• ArrayIrregular
• Grid2D
• GridIrregular

And so on.

They serve an important purpose, unifying the API and abstractions in a way which ensures a user can understand
that data and grids can be paired to something uniform or not. Furthermore, the slam / native API is important
in making both accessible, and streamlining how masked data vectors are stored.

First, we should assess if this code can be simplified at all or if its acceptable. I dont have a better idea.

You would probably benefit from reading @autolens_workspace/scripts/guides/data_structures.py to see how a user
interfaces with these objects.

However, things get more complex, as these objects are used to define mappings at the profile level of
@PyAutoGalaxy/autogalaxy/profiles. For example for this function:

class Isothermal(PowerLaw):
def init(self, centre, ell_comps, einstein_radius):
super().init(centre=centre, ell_comps=ell_comps, einstein_radius=einstein_radius, slope=2.0)

@aa.grid_dec.to_vector_yx
@aa.grid_dec.transform
def deflections_yx_2d_from(self, grid, xp=np, **kwargs):
    ...

The decorator @aa.grid_dec.to_vector_yx is used to understand that for this function, the result
that comes out must be a VectorYX object. It handles more typing, for example if a Grid2DIrregular comes in
a VectorYXIrregular comes out, but a Grid2D produces a VectorYX object.

There is also behaviour where if a numpy ndarray comes in, a numpy ndarray comes out without type casting,
with the same behaviour for a JAX array.

The problem is really just how complex things got in this decorator, which is all handled at
@PyAutoArray/autoarray/structures/decorators. Its complicated, messy and hard to trace.

So, can you give me your assessment of whether there's a quite large, sweeping restructure that can simplify this
code but retain the desired functionality and behaviour? Think hard, this could require a good chunk of planning
and no doubt extensive testing after!