refactor: reduce magic in transform decorator

[Jammy2211]

Overview

The @aa.grid_dec.transform decorator reduces repeated code across ~58 profile methods but relies on implicit is_transformed kwargs and requires manual back-rotation for deflection vectors. This refactor makes the decorator less "magical" while keeping its DRY benefits, split into two phases.

Plan

• Phase 1: Move is_transformed from kwargs onto a grid property, add decorator stacking validation, and update all profile methods to use the new pattern
• Phase 2: Add optional automatic back-rotation for vector outputs to the transform decorator, eliminating manual rotated_grid_from_reference_frame_from calls in deflection methods. Validate with direct unit tests first before rolling out across all profiles.
• Update the add_a_profile.py workspace guide to reflect the simplified API

Detailed implementation plan

Affected Repositories

• PyAutoArray (primary)
• PyAutoGalaxy
• autolens_workspace

Work Classification

Library (both phases), then workspace guide update

Branch Survey

Repository	Current Branch	Dirty?
PyAutoArray	main	clean
PyAutoGalaxy	main	clean
autolens_workspace	main	clean

Suggested branch: feature/transform-decorator
Worktree root: ~/Code/PyAutoLabs-wt/transform-decorator/ (created later by /start_library)

Phase 1: Explicit transform state + validation

1. Add is_transformed property to grid classes (autoarray/structures/grids/)

   • Add boolean attribute to Grid2D, Grid2DIrregular, and base grid classes
   • Ensure it's preserved through grid operations (slicing, copying)

2. Update the transform decorator (autoarray/structures/decorators/transform.py)

   • Read grid.is_transformed instead of kwargs.get("is_transformed")
   • Set is_transformed = True on the transformed grid copy
   • Keep backward compat with kwargs during transition

3. Add decorator stacking validation (autoarray/structures/decorators/abstract.py)

   • Tag decorators with priority; raise ValueError on wrong order

4. Update profile methods in PyAutoGalaxy (autogalaxy/profiles/)

   • Remove is_transformed kwarg propagation where it only served this purpose
   • Verify all existing tests still pass

Phase 2: Automatic back-rotation for deflection vectors

1. Write direct unit tests first against a few known profiles (e.g. Isothermal, NFW)

   • Compute deflections with current manual back-rotation
   • Compute deflections with new automatic back-rotation
   • Assert results match to numerical precision

2. Enhance the transform decorator (autoarray/structures/decorators/transform.py)

   • Add parameter to signal that output is a vector requiring back-rotation
   • Implement inverse rotation using rotated_grid_from_reference_frame_from logic
   • The @aa.grid_dec.to_vector_yx decorator or a new combined decorator could handle this

3. Update deflection methods (~15-20 methods across autogalaxy/profiles/mass/)

   • Remove manual rotated_grid_from_reference_frame_from calls
   • Use new decorator parameter for automatic back-rotation

4. Update add_a_profile.py guide in autolens_workspace

   • Simplify the "Do I Rotate Back?" section
   • Show the new pattern

Key Files

• autoarray/structures/decorators/transform.py — decorator implementation
• autoarray/structures/decorators/to_vector_yx.py — vector output decorator
• autoarray/structures/grids/ — grid classes for is_transformed property
• autogalaxy/profiles/geometry_profiles.py — transform logic
• autogalaxy/profiles/mass/total/isothermal.py — example profile to update
• autolens_workspace/scripts/guides/advanced/add_a_profile.py — user guide

Original Prompt

Click to expand starting prompt

The transform decorator is used on nearly every mass and light profile in @PyAutoGalaxy/autogalaxy/profiles, for example: Isothermal(PowerLaw) with @aa.grid_dec.transform on deflections_yx_2d_from.

The decorator shifts the input grid to the profile centre and rotates by elliptical components. It has "magic" via is_transformed kwargs to prevent double-transforms. Users have reported not understanding where transforms are performed. The trade-off is DRY code vs readability/transparency.

Decision: keep the decorator but reduce the magic — move is_transformed to a grid property, add optional automatic back-rotation for vector outputs, and add decorator stacking validation.

[Jammy2211]

Smoke Test Results — 2026-04-13

Workspace	Passed	Failed	Total
autofit_workspace	6	1	7
autogalaxy_workspace	4	2	6
autolens_workspace	6	1	7
autolens_workspace_test	1	7	8

All failures are pre-existing and unrelated to the transform-decorator changes:

• autofit/cookbooks/samples.py — bypass test mode generates 2 samples, script expects 5 (IndexError)
• autogalaxy/imaging/start_here.py — missing mask_extra_galaxies.fits dataset file
• autogalaxy/interferometer/start_here.py — missing sma.fits UV wavelength file
• autolens/interferometer/modeling.py — same missing sma.fits
• autolens_workspace_test (7 scripts) — missing dataset files and small-dataset mask/array shape mismatches

Scripts that exercise the transform-decorator changes (imaging modeling/fit, galaxies guides, group/multi modeling, cookbook) all pass.

[Jammy2211]

Shipped — 2026-04-13

PRs

• refactor: reduce magic in transform decorator #272
• refactor: use auto back-rotation in deflection methods PyAutoGalaxy#347
• docs: update add_a_profile guide for rotate_back autolens_workspace#54

Summary

Refactored the @transform decorator to support optional rotate_back=True for automatic back-rotation of vector quantities (deflection angles). Moved is_transformed from kwargs to a property on grid objects. Removed ~47 lines of manual rotated_grid_from_reference_frame_from calls across 12 mass profile files in PyAutoGalaxy, replacing them with @transform(rotate_back=True). Updated the add_a_profile.py workspace guide with precise frame-convention documentation.

Session Notes

• Shear methods retain manual 2θ rotation (spin-2 transformation law not handled by rotate_back)
• MGE methods retain manual rotation (uses a different object's rotation method)
• 12 regression tests added with exact numerical values for Isothermal, NFW, PowerLaw, ExternalShear, Gaussian