deprecate some shorthands in specifying beams in yaml files

docs/example_configs/baseline_lite.csv

@@ -2,5 +2,5 @@ Name Number   BeamID   E          N          U
 
 ANT1        0        0     0.0000   0.0000  0.0000
 ANT2        1        0     50.000   0.0000  0.0000
-ANT3        2        1     0.0000   -50.00  0.0000
-ANT4        3        1     26.000   -26.00  0.0000
+ANT3        2        2     0.0000   -50.00  0.0000
+ANT4        3        2     26.000   -26.00  0.0000

docs/example_configs/bl_lite_mixed.yaml

@@ -1,21 +1,19 @@
 beam_paths:
-  0: hera.beamfits
+  0:
+    filename: hera.beamfits
   1:
+    filename: mwa_full_EE_test.h5
+    pixels_per_deg: 1
+    freq_range: [100.e+6, 200.e+6]
+  2:
     type: airy
     diameter: 16
-  2:
+  3:
     type: gaussian
     sigma: 0.03
-  3: airy
   4:
     type: gaussian
     diameter: 14
-  5: gaussian
-  6:
-    filename: mwa_full_EE_test.h5
-    pixels_per_deg: 1
-    freq_range: [100.e+6, 200.e+6]
-diameter: 12
 spline_interp_opts:
         kx: 4
         ky: 4

docs/parameter_files.rst

@@ -180,63 +180,59 @@ Telescope Configuration
     .. literalinclude:: example_configs/bl_lite_mixed.yaml
 
     This yaml file provides the telescope name, location in latitude/longitude/altitude
-    in degrees/degrees/meters (respectively), and the `beam dictionary`.
-    In this case we have 7 different types of beams with beam IDs running from
-    0 to 6:
-
-      - 0 is the UVBeam file hera.beamfits
-      - 1 is an Airy disk with diameter 16 m
-      - 2 is a Gaussian beam with sigma 0.03 radians (for the E-Field beam)
-      - 3 is another Airy beam with diameter 12 m
-      - 4 is a Gaussian with diameter 14 m
-      - 5 is a Gaussian with diameter 12 m.
-      - 6 is a UVBeam (for the MWA) with some keywords specified to pass to UVBeam.read
-
-    When specifying a shape parameter for a specific beam_id, the beam type
-    needs to be specified using the type keyword (rather than on the same line
-    as the beam_id) and then the shape keyword can be specified in the next
-    line at the same indent level. When no shape parameter is added in the
-    beam_dictionary (as with 3), pyuvsim will look for a default parameter below.
-    So in this case, the beam_id == 3 and 5 end up with a diameter of 12 m.
+    in degrees/degrees/meters (respectively), and the beam dictionary
+    (the ``beam_paths`` section).
+    In this case we have 5 different types of beams with beam IDs running from
+    0 to 4:
+
+      - 0: a UVBeam from the file `hera.beamfits`
+      - 1: a UVBeam (for the MWA) with some keywords specified to pass to ``UVBeam.read``
+      - 2: an analytic Airy disk with diameter 16 m
+      - 3: an analytic Gaussian beam with sigma 0.03 radians (for the E-Field beam)
+      - 4: an analytic Gaussian with diameter 14 m
+
+    The parameters for each beam depends on whether it is a UVBeam or an analytic
+    beam. UVBeams must have a `filename` parameter and they can optionally have
+    any other parameter that can be passed to the ``UVBeam.read`` method.
+    Analytic beams must have a `type` parameter and can have parameters specifying
+    shapes as appropriate for their type.
     The dictionary only needs to be as long as the number of unique beams used
     in the array, while the layout file specifies which antennas will use which
     beam type. This allows for a mixture of beams to be used, as in this example.
-    Unassigned beams will be ignored (the given layout file only uses beam IDs 0 and 1).
+    Unassigned beams will be ignored (the given layout file only uses beamIDs 0 and 2).
 
-    `freq_interp_kind` sets the type of frequency interpolation for all UVBeam
-    objects defined in the beam list (see documentation on UVBeam for options).
+    Analytic beams may require shape parameters depending on their type.
 
-    The `spline_interp_opts` keyword lets the user set the order on the angular
-    interpolating polynomial spline function. By default, it is cubic.
-
-    The `select` options allows for doing partial reading UVBeam files.
-    This can include any selection parameter accepted by UVBeam.read and it
-    will apply to all UVBeams in the file. It can also take a `freq_buffer`
-    parameter which is used to set the freq_range on read so that only
-    frequencies within `freq_buffer` of the min and max of the simulated
-    frequencies will be read during setup. This can help reduce peak memory
-    usage.
-
-    UVBeams can have parameters that will be passed to the UVBeam.read method.
-    These can be any parameters accepted by the UVBeam.read method. If the same
-    parameter is passed for a specific UVBeam and to the `select` section described
-    above, the values passed for the specific UVBeam will supercede the matching
-    `select` parameters for that beam.
-
-    Analytic beams may require additional parameters.
-
-    - uniform = The same response in all directions. No additional parameters.
-    - gaussian = Gaussian function shaped beam. Requires either an antenna `diameter`
+    - airy: Airy disk (ie, diffraction pattern of a circular aperture). Requires an
+      antenna diameter and is inherently chromatic.
+    - gaussian: Gaussian function shaped beam. Requires either an antenna `diameter`
       (in meters) or a standard deviation `sigma` (in radians). Gaussian beams
       specified by a diameter will have their width matched to an Airy beam at
-      each simulated frequency, so it is inherently chromatic. For Gaussian beams
+      each simulated frequency, so are inherently chromatic. For Gaussian beams
       specified with `sigma`, `sigma` sets the width of the E-Field beam in zenith angle.
       If only `sigma` is specified, the beam is achromatic, optionally both the
       `spectral_index` and `reference_frequency` parameters can be set to generate
       a chromatic beam with standard deviation defined by a power law:
       `stddev(f) = sigma * (f/ref_freq)**(spectral_index)`
-    - airy = Airy disk (ie, diffraction pattern of a circular aperture). Requires an
-      antenna diameter and is inherently chromatic.
+    - uniform: The same response in all directions. No additional parameters.
+
+    There are also some global parameters that apply to all the UVBeams:
+
+      - `freq_interp_kind` sets the type of frequency interpolation for all UVBeam
+        objects defined in the beam list (see documentation on UVBeam for options).
+
+      - The `spline_interp_opts` keyword lets the user set the order on the angular
+        interpolating polynomial spline function. By default, it is cubic.
+
+      - The `select` section allows for doing partial reading UVBeam files.
+        This can include any selection parameter accepted by UVBeam.read.
+        It can also take a `freq_buffer` parameter which is used to set the
+        `freq_range` on read so that only frequencies within `freq_buffer` of the
+        min and max of the simulated frequencies will be read during setup. This
+        can help reduce peak memory usage. Note that if any of the same `select`
+        parameters are passed for a specific UVBeam and to the `select` section,
+        the values passed for the specific UVBeam will supercede the values in the
+        `select` section.
 
     The figure below shows the array created by these configurations, with beam type
     indicated by color.

pyuvsim/data/mwa128_config.yaml

@@ -1,4 +1,5 @@
 beam_paths:
-    0 : 'uniform'
+    0 :
+        type: uniform
 telescope_location: (-26.70331940555556, 116.67081523611111, 377.82699999958277)
 telescope_name: MWA

pyuvsim/data/test_config/28m_triangle_10time_10chan.yaml

@@ -1,10 +1,13 @@
 beam_paths:
-  0: HERA_NicCST.beamfits
-  1: 'uniform'
+  0:
+    filename: HERA_NicCST.beamfits
+  1:
+    type: uniform
   2:
-    type: 'gaussian'
+    type: gaussian
     sigma: 0.02
-  3: 'airy'
-diameter: 14.6
+  3:
+    type: airy
+    diameter: 14.6
 telescope_location: (-30.721527777777847, 21.428305555555557, 1073.0000000046566)
 telescope_name: HERA

pyuvsim/data/test_config/28m_triangle_10time_10chan_gaussnoshape.yaml

@@ -1,7 +1,11 @@
 beam_paths:
-  0: HERA_NicCST.beamfits
-  1: 'uniform'
-  2: 'gaussian'
-  3: 'gaussian'
+  0:
+    filename: HERA_NicCST.beamfits
+  1:
+    type: uniform
+  2:
+    type: gaussian
+  3:
+    type: gaussian
 telescope_location: (-30.721527777777847, 21.428305555555557, 1073.0000000046566)
 telescope_name: HERA

pyuvsim/data/test_config/28m_triangle_10time_10chan_nodiameter.yaml

@@ -1,8 +1,12 @@
 beam_paths:
-  0: HERA_NicCST.beamfits
-  1: 'uniform'
-  2: 'gaussian'
-  3: 'airy'
-sigma: 0.02
+  0:
+    filename: HERA_NicCST.beamfits
+  1:
+    type: uniform
+  2:
+    type: gaussian
+    sigma: 0.02
+  3:
+    type: airy
 telescope_location: (-30.721527777777847, 21.428305555555557, 1073.0000000046566)
 telescope_name: HERA

pyuvsim/data/test_config/28m_triangle_10time_10chan_nofile.yaml

@@ -1,9 +1,13 @@
 beam_paths:
-  0: filethatdoesnotexist.beamfits
-  1: 'uniform'
-  2: 'gaussian'
-  3: 'airy'
-sigma: 0.02
-diameter: 14.6
+  0:
+    filename: filethatdoesnotexist.beamfits
+  1:
+    type: uniform
+  2:
+    type: gaussian
+    sigma: 0.02
+  3:
+    type: airy
+    diameter: 14.6
 telescope_location: (-30.721527777777847, 21.428305555555557, 1073.0000000046566)
 telescope_name: HERA

pyuvsim/data/tranquility_config.yaml

@@ -1,5 +1,6 @@
 beam_paths:
-    0 : 'uniform'
+    0 :
+        type: uniform
 telescope_location: (0.6875, 24.433, 0)
 world: 'moon'
 telescope_name: apollo11

pyuvsim/simsetup.py

@@ -1002,12 +1002,30 @@ def _construct_beam_list(beam_ids, telconfig, freq_range=None, force_check=False
     """Construct BeamList."""
     beam_list = []
     uvb_read_kwargs = {}
+
+    # possible global shape options
+    if "diameter" in telconfig.keys() or "sigma" in telconfig.keys():
+        warnings.warn(
+            "Beam shape options diameter and sigma should be specified per beamID "
+            "in the 'beam_paths' section not as globals. For examples see the "
+            "parameter_files documentation. This will become an error in version 1.4",
+            DeprecationWarning,
+        )
+
     for beamID in beam_ids:
         beam_model = telconfig['beam_paths'][beamID]
 
         if not isinstance(beam_model, (str, dict)):
             raise ValueError('Beam model is not properly specified in telescope config file.')
 
+        if isinstance(beam_model, str):
+            warnings.warn(
+                "Entries in 'beam_paths' can no longer be specified as simple strings, "
+                "they must be parsed as dicts. For examples see the parameter_files "
+                "documentation. This will become an error in version 1.4",
+                DeprecationWarning,
+            )
+
         if isinstance(beam_model, str) and beam_model not in AnalyticBeam.supported_types:
             # this is the path to a UVBeam readable file
             beam_file = _check_uvbeam_file(beam_model)
@@ -2170,7 +2188,7 @@ def uvdata_to_telescope_config(
             os.path.join(path_out, uvdata_in.telescope_name + "_layout.csv"))
         layout_csv_name = os.path.basename(layout_csv_path)
 
-    antpos_enu, antenna_numbers = uvdata_in.get_ENU_antpos()
+    antpos_enu, _ = uvdata_in.get_ENU_antpos()
 
     _write_layout_csv(
         os.path.join(path_out, layout_csv_name),
@@ -2182,7 +2200,7 @@ def uvdata_to_telescope_config(
         "telescope_name": uvdata_in.telescope_name,
         "telescope_location": repr(tuple(uvdata_in.telescope_location_lat_lon_alt_degrees)),
         "Nants": uvdata_in.Nants_telescope,
-        "beam_paths": {0: beam_filepath}
+        "beam_paths": {0: {"filename": beam_filepath}}
     }
 
     with open(os.path.join(path_out, telescope_config_name), 'w+') as yfile:

pyuvsim/tests/test_run.py

@@ -139,7 +139,7 @@ def test_analytic_diffuse(model, tmpdir):
     herauniform_path = str(tmpdir.join('hera_uniform.yaml'))
 
     teleconfig = {
-        'beam_paths': {0: 'uniform'},
+        'beam_paths': {0: {"type": "uniform"}},
         'telescope_location': "(-30.72153, 21.42830, 1073.0)",
         'telescope_name': 'HERA'
     }
@@ -234,7 +234,7 @@ def test_run_paramdict_uvsim(rename_beamfits, tmp_path):
         # change the beam file name to .uvbeam
         with open(new_telescope_param_file, 'r') as pfile:
             tele_param_dict = yaml.safe_load(pfile)
-            tele_param_dict["beam_paths"][0] = new_beam_file
+            tele_param_dict["beam_paths"][0] = {"filename": new_beam_file}
 
         with open(new_telescope_param_file, 'w') as yfile:
             yaml.dump(tele_param_dict, yfile, default_flow_style=False)