use better names for the new components

feed_aligned_response and feed_aligned_projection

Author: bhazelton

src/pyuvdata/analytic_beam.py

@@ -391,11 +391,11 @@ def _get_empty_data_array(
         self,
         grid_shape: tuple[int, int],
         beam_type: Literal[
-            "efield", "power", "feed_iresponse", "feed_projection"
+            "efield", "power", "feed_aligned_response", "feed_aligned_projection"
         ] = "efield",
     ) -> FloatArray:
         """Get the empty data to fill in the eval methods."""
-        if beam_type in ["efield", "feed_projection"]:
+        if beam_type in ["efield", "feed_aligned_projection"]:
             return np.zeros(
                 (self.Naxes_vec, self.Nfeeds, *grid_shape), dtype=np.complex128
             )
@@ -404,7 +404,7 @@ def _get_empty_data_array(
                 (1, self.Npols, *grid_shape),
                 dtype=np.complex128 if self.Npols > self.Nfeeds else np.float64,
             )
-        elif beam_type == "feed_iresponse":
+        elif beam_type == "feed_aligned_response":
             return np.zeros((1, self.Nfeeds, *grid_shape), dtype=np.complex128)
 
     def efield_eval(
@@ -516,11 +516,23 @@ def power_eval(
 
             return data_array
 
-    def feed_iresponse_eval(
+    def feed_aligned_response_eval(
         self, *, az_array: FloatArray, za_array: FloatArray, freq_array: FloatArray
     ) -> FloatArray:
         """
-        Evaluate the feed I response at the given coordinates.
+        Evaluate the feed aligned response at the given coordinates.
+
+        The feed aligned response is the complex response of each instrumental
+        feed to electric fields aligned with it -- i.e. after projecting electric
+        fields to directions aligned with the feeds (these directions are
+        non-orthogonal in many directions on the sky even though the feeds are
+        generally physically orthogonal). Since the projection has already happened,
+        the feed aligned response only has a feed index, no vector component axis.
+        Non-zero phase is caused by time delays which can vary spatially but do
+        not depend on incident polarization.
+
+        Unpolarized light is equally spread among all polarization orientations,
+        so the feed aligned response can be used as the response to unpolarized light.
 
         Parameters
         ----------
@@ -544,11 +556,11 @@ def feed_iresponse_eval(
             az_array=az_array, za_array=za_array, freq_array=freq_array
         )
 
-        if hasattr(self, "_feed_iresponse_eval"):
+        if hasattr(self, "_feed_aligned_response_eval"):
             za_grid, _ = np.meshgrid(za_array, freq_array)
             az_grid, f_grid = np.meshgrid(az_array, freq_array)
 
-            return self._feed_iresponse_eval(
+            return self._feed_aligned_response_eval(
                 az_grid=az_grid, za_grid=za_grid, f_grid=f_grid
             ).astype(complex)
         else:
@@ -574,11 +586,18 @@ def feed_iresponse_eval(
 
             return data_array.astype(complex)
 
-    def feed_projection_eval(
+    def feed_aligned_projection_eval(
         self, *, az_array: FloatArray, za_array: FloatArray, freq_array: FloatArray
     ) -> FloatArray:
         """
-        Evaluate the feed projection at the given coordinates.
+        Evaluate the feed aligned projection at the given coordinates.
+
+        The feed aligned projection is the projection from celestial polarization
+        vector components (orthogonal on the sky) to instrumental feed vector
+        components (often non-orthogonal on the sky). This is similar to a
+        rotation matrix in that it just converts between coordinate systems
+        (the magnitude of the response is removed), but is not unitary because
+        the projection of the feeds are not orthogonal in all directions on the sky.
 
         Parameters
         ----------
@@ -605,8 +624,8 @@ def feed_projection_eval(
         za_grid, _ = np.meshgrid(za_array, freq_array)
         az_grid, f_grid = np.meshgrid(az_array, freq_array)
 
-        if hasattr(self, "_feed_projection_eval"):
-            return self._feed_projection_eval(
+        if hasattr(self, "_feed_aligned_projection_eval"):
+            return self._feed_aligned_projection_eval(
                 az_grid=az_grid, za_grid=za_grid, f_grid=f_grid
             ).astype(complex)
         else:
@@ -615,7 +634,7 @@ def feed_projection_eval(
             )
 
             # set f to the magnitude of the I response, assume no time delays
-            f_vals = self.feed_iresponse_eval(
+            f_vals = self.feed_aligned_response_eval(
                 az_array=az_array, za_array=za_array, freq_array=freq_array
             )
             data_array = self._get_empty_data_array(az_grid.shape)
@@ -631,7 +650,7 @@ def to_uvbeam(
         self,
         freq_array: FloatArray,
         beam_type: Literal[
-            "efield", "power", "feed_iresponse", "feed_projection"
+            "efield", "power", "feed_aligned_response", "feed_aligned_projection"
         ] = "efield",
         pixel_coordinate_system: (
             Literal["az_za", "orthoslant_zenith", "healpix"] | None
@@ -653,7 +672,8 @@ def to_uvbeam(
         freq_array : ndarray of float
             Array of frequencies in Hz to evaluate the beam at.
         beam_type : str
-            Beam type, one of "efield", "power", "feed_iresponse" or "feed_projection".
+            Beam type, one of "efield", "power", "feed_aligned_response" or
+            "feed_aligned_projection".
         pixel_coordinate_system : str
             Pixel coordinate system, options are "az_za", "orthoslant_zenith" and
             "healpix". Forced to be "healpix" if ``nside`` is given and by
@@ -676,7 +696,12 @@ def to_uvbeam(
             Healpix ordering parameter, defaults to "ring" if nside is provided.
 
         """
-        allowed_beam_types = ["efield", "power", "feed_iresponse", "feed_projection"]
+        allowed_beam_types = [
+            "efield",
+            "power",
+            "feed_aligned_response",
+            "feed_aligned_projection",
+        ]
         if beam_type not in allowed_beam_types:
             raise ValueError(f"Beam type must be one of {allowed_beam_types}")
 
@@ -761,7 +786,7 @@ def plot(
         self,
         *,
         beam_type: Literal[
-            "efield", "power", "feed_iresponse", "feed_projection"
+            "efield", "power", "feed_aligned_response", "feed_aligned_projection"
         ] = "efield",
         freq: float,
         complex_type: str = "real",
@@ -782,7 +807,8 @@ def plot(
         Parameters
         ----------
         beam_type : str
-            Beam type, one of "efield", "power", "feed_iresponse" or "feed_projection".
+            Beam type, one of "efield", "power", "feed_aligned_response" or
+            "feed_aligned_projection".
         freq : int
             The frequency index to plot.
         complex_type : str

src/pyuvdata/beam_interface.py

@@ -38,7 +38,8 @@ class BeamInterface:
         Beam object to use for computations. If a BeamInterface is passed, a new
         view of the same object is created.
     beam_type : str
-        The beam type, one of "efield", "power", "feed_iresponse" or "feed_projection".
+        The beam type, one of "efield", "power", "feed_aligned_response" or
+        "feed_aligned_projection".
     include_cross_pols : bool
         Option to include the cross polarized beams (e.g. xy and yx or en and ne).
         Used if beam is a UVBeam and and the input UVBeam is an Efield beam but
@@ -49,7 +50,8 @@ class BeamInterface:
 
     beam: AnalyticBeam | UVBeam
     beam_type: (
-        Literal["efield", "power", "feed_iresponse", "feed_projection"] | None
+        Literal["efield", "power", "feed_aligned_response", "feed_aligned_projection"]
+        | None
     ) = None
     include_cross_pols: InitVar[bool] = True
 
@@ -82,8 +84,8 @@ def __post_init__(self, include_cross_pols: bool):
             elif self.beam.beam_type == "efield":
                 conv_func = {
                     "power": "efield_to_power",
-                    "feed_iresponse": "efield_to_feed_iresponse",
-                    "feed_projection": "efield_to_feed_projection",
+                    "feed_aligned_response": "efield_to_feed_aligned_response",
+                    "feed_aligned_projection": "efield_to_feed_aligned_projection",
                 }
                 warnings.warn(
                     "Input beam is an efield UVBeam but beam_type is specified as "

src/pyuvdata/utils/plotting.py

@@ -414,7 +414,7 @@ def beam_plot(
         freq_title = freq
 
         naxes_vec = beam_obj.Naxes_vec
-        if beam_type in ["power", "feed_iresponse"]:
+        if beam_type in ["power", "feed_aligned_response"]:
             naxes_vec = 1
         reg_grid = True
 
@@ -440,9 +440,9 @@ def beam_plot(
         beam_type_label = "power"
     elif beam_type == "efield":
         beam_type_label = "E-field"
-    elif beam_type == "feed_iresponse":
+    elif beam_type == "feed_aligned_response":
         beam_type_label = "Feed I response"
-    elif beam_type == "feed_projection":
+    elif beam_type == "feed_aligned_projection":
         beam_type_label = "Feed projection"
 
     plot_beam_arrays(

src/pyuvdata/uvbeam/initializers.py

@@ -24,7 +24,9 @@ def new_uvbeam(
     feed_version: str = "0.0",
     model_name: str = "default",
     model_version: str = "0.0",
-    beam_type: Literal["efield", "power", "feed_iresponse", "feed_projection"] = None,
+    beam_type: Literal[
+        "efield", "power", "feed_aligned_response", "feed_aligned_projection"
+    ] = None,
     feed_array: StrArray | None = None,
     feed_angle: FloatArray | None = None,
     mount_type: str | None = "fixed",
@@ -80,8 +82,9 @@ def new_uvbeam(
     model_version: str
         Version of the beam model.
     beam_type : str
-        Beam type, one of "efield", "power", "feed_iresponse" or "feed_projection".
-        Defaults to "power" if polarization_array is provided and "efield" otherwise.
+        Beam type, one of "efield", "power", "feed_aligned_response" or
+        "feed_aligned_projection". Defaults to "power" if polarization_array is
+        provided and "efield" otherwise.
     feed_array : ndarray of str
         Array of feed orientations. Options are: n/e or x/y or r/l.
     feed_angle : ndarray of float
@@ -268,7 +271,7 @@ def new_uvbeam(
             "Either nside or both axis1_array and axis2_array must be provided."
         )
 
-    if uvb.beam_type in ["power", "feed_iresponse"]:
+    if uvb.beam_type in ["power", "feed_aligned_response"]:
         uvb.Naxes_vec = 1
 
     uvb._set_cs_params()
@@ -305,7 +308,7 @@ def new_uvbeam(
                 f"expected shape {bv_shape}."
             )
         uvb.basis_vector_array = basis_vector_array
-    elif uvb.beam_type in ["efield", "feed_projection"]:
+    elif uvb.beam_type in ["efield", "feed_aligned_projection"]:
         if uvb.pixel_coordinate_system == "healpix":
             basis_vector_array = np.zeros(
                 (uvb.Naxes_vec, uvb.Ncomponents_vec, uvb.Npixels), dtype=float