Merge pull request #246 from HERA-Team/mutual_coupling

feat: mutual coupling a la Josaitis+22

CHANGELOG.rst

@@ -5,6 +5,24 @@ Changelog
 dev-version
 ===========
 
+v3.1.0 [2023.01.17]
+===================
+
+Added
+-----
+- :class:`~.sigchain.MutualCoupling` class that simulates the systematic described in Josaitis
+  et al. 2021.
+- New class attributes for the :class:`~.SimulationComponent` class:
+    - ``return_type`` specifies what type of return value to expect;
+    - ``attrs_to_pull`` specifies which ``Simulator`` attributes to use.
+- Some helper functions for :class:`~.sigchain.MutualCoupling` matrix multiplications.
+- More attributes from the underlying ``UVData`` object exposed to the :class:`~.Simulator`.
+
+Changed
+-------
+- ``Simulator._update_args`` logic has been improved.
+- :class:`~.Simulator` attributes ``lsts``, ``times``, and ``freqs`` are no longer cached.
+
 v3.0.0
 ======
 
@@ -142,7 +160,7 @@ Added
 
 Fixed
 -----
-- default ``feed_array` for ``PolyBeam`` fixed.
+- default ``feed_array`` for ``PolyBeam`` fixed.
 
 Changed
 -------

hera_sim/components.py

@@ -18,7 +18,7 @@ class SimulationComponent(metaclass=ABCMeta):
 
     This class serves two main purposes:
         - Provide a simple interface for discovering simulation
-          component models (see :meth:`~list_discoverable_components`").
+          component models (see :meth:`~list_discoverable_components`).
         - Ensure that each subclass can create abstract methods.
 
     The :meth:`~component`: class decorator provides a simple way of
@@ -29,20 +29,30 @@ class SimulationComponent(metaclass=ABCMeta):
     ----------
     is_multiplicative
         Specifies whether the model ``cls`` is a multiplicative
-        effect. This parameter lets the :class:`~hera_sim.simulate.Simulator`:
+        effect. This parameter lets the :class:`~hera_sim.simulate.Simulator`
         class determine how to apply the effect simulated by
         ``cls``. Default setting is False (i.e. the model is
         assumed to be additive unless specified otherwise).
+    return_type
+        Whether the returned result is per-antenna, per-baseline, or the full
+        data array. This tells the :class:`~hera_sim.simulate.Simulator` how
+        it should handle the returned result.
+    attrs_to_pull
+        Dictionary mapping parameter names to :class:`~hera_sim.simulate.Simulator`
+        attributes to be retrieved when setting up for simulation.
     """
 
     #: Whether this systematic multiplies existing visibilities
     is_multiplicative: bool = False
+    #: Whether the returned value is per-antenna, per-baseline, or the full array
+    return_type: str | None = None
+    # This isn't exactly safe, but different instances of a class should
+    # have the same call signature, so this should actually be OK.
+    #: Mapping between parameter names and Simulator attributes
+    attrs_to_pull: dict = {}
 
     _alias: tuple[str] = tuple()
 
-    # Keyword arguments for the Simulator to extract from the data
-    _extract_kwargs = set()
-
     def __init_subclass__(cls, is_abstract: bool = False):
         """Provide some useful augmentations to subclasses.
 

hera_sim/eor.py

@@ -49,6 +49,10 @@ class NoiselikeEoR(EoR):
 
     _alias = ("noiselike_eor",)
     is_smooth_in_freq = False
+    return_type = "per_baseline"
+    attrs_to_pull = dict(
+        bl_vec=None,
+    )
 
     def __init__(
         self,

hera_sim/foregrounds.py

@@ -65,6 +65,10 @@ class DiffuseForeground(Foreground):
 
     _alias = ("diffuse_foreground",)
     is_smooth_in_freq = True
+    return_type = "per_baseline"
+    attrs_to_pull = dict(
+        bl_vec=None,
+    )
 
     def __init__(
         self,
@@ -190,6 +194,10 @@ class PointSourceForeground(Foreground):
     """
 
     _alias = ("pntsrc_foreground",)
+    return_type = "per_baseline"
+    attrs_to_pull = dict(
+        bl_vec=None,
+    )
 
     def __init__(
         self,

hera_sim/interpolators.py

@@ -48,7 +48,7 @@ def _read(datafile):
     elif ext == ".npz":
         return _read_npz(datafile)
     else:
-        raise ValueError(f"File type '{ext}' not supported.")
+        raise ValueError(f"File type {ext!r} not supported.")
 
 
 class Interpolator:

hera_sim/noise.py

@@ -57,7 +57,11 @@ class ThermalNoise(Noise):
     """
 
     _alias = ("thermal_noise",)
-    _extract_kwargs = {"autovis", "antpair"}
+    return_type = "per_baseline"
+    attrs_to_pull = dict(
+        autovis=None,
+        antpair=None,
+    )
 
     def __init__(
         self,

hera_sim/rfi.py

@@ -130,6 +130,7 @@ class Stations(RFI):
     """
 
     _alias = ("rfi_stations",)
+    return_type = "per_baseline"
 
     def __init__(self, stations=None):
         super().__init__(stations=stations)
@@ -201,6 +202,7 @@ class Impulse(RFI):
     """
 
     _alias = ("rfi_impulse",)
+    return_type = "per_baseline"
 
     def __init__(self, impulse_chance=0.001, impulse_strength=20.0):
         super().__init__(
@@ -264,6 +266,7 @@ class Scatter(RFI):
     """
 
     _alias = ("rfi_scatter",)
+    return_type = "per_baseline"
 
     def __init__(self, scatter_chance=0.0001, scatter_strength=10.0, scatter_std=10.0):
         super().__init__(
@@ -330,6 +333,7 @@ class DTV(RFI):
     """
 
     _alias = ("rfi_dtv",)
+    return_type = "per_baseline"
 
     def __init__(
         self,