docs: precise frame-convention docstrings for rotate_back

Clarify that rotate_back is needed when vector components are expressed
in the profile's rotated frame, not unconditionally for all vectors.
Document scalar, vector, and spin-2 transformation conventions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

autoarray/structures/decorators/transform.py

@@ -20,19 +20,40 @@ def convergence_2d_from(self, grid, xp=np, **kwargs): ...
         @transform(rotate_back=True)
         def deflections_yx_2d_from(self, grid, xp=np, **kwargs): ...
 
-    When ``rotate_back=True``, after the decorated function returns its result the decorator automatically
-    rotates the output vector back from the profile's reference frame to the original observer frame.
-    This eliminates the need for deflection methods to manually call
-    ``self.rotated_grid_from_reference_frame_from``.
+    **Frame conventions and rotate_back**
+
+    This decorator transforms the input grid into the profile's reference frame (centred on the
+    profile centre and rotated by its position angle) before calling the decorated function.
+
+    For **scalar** quantities (convergence, potential), the returned value is frame-invariant — no
+    back-rotation is needed, so use ``@transform`` without ``rotate_back``.
+
+    For **vector** quantities (e.g. deflection angles), whether back-rotation is needed depends on
+    which frame the returned components are expressed in:
+
+    - If the function computes vector components using the rotated grid coordinates (i.e. the
+      components are expressed in the profile's frame), they must be rotated back to the observer
+      frame before use in ray-tracing. Set ``rotate_back=True`` for this case.
+
+    - If the function reconstructs observer-frame components from scalar quantities (e.g. computing
+      a radial deflection magnitude and converting to Cartesian using observer-frame geometry), the
+      result is already in the observer frame and ``rotate_back`` should remain ``False``.
+
+    When ``rotate_back=True``, the decorator calls ``obj.rotated_grid_from_reference_frame_from``
+    on the result after evaluation, applying the inverse rotation by the profile's position angle.
+
+    For **spin-2** quantities (shear), the transformation law uses twice the profile angle. This
+    is not handled by ``rotate_back`` — shear methods must apply the 2-theta rotation manually.
 
     Parameters
     ----------
     func
         A function where the input grid is the grid whose coordinates are transformed.
     rotate_back
-        If ``True``, the result is rotated back from the profile's reference frame after evaluation.
-        Use this for functions that return vector quantities (e.g. deflection angles) computed in the
-        profile's rotated frame.
+        If ``True``, the result is rotated back from the profile's reference frame after
+        evaluation. Use this when the decorated function returns vector components that were
+        computed in the profile's rotated coordinate basis and need to be expressed in the
+        original observer frame.
 
     Returns
     -------