Add docs

docs/analytic_beams.rst

@@ -0,0 +1,77 @@
+Analytic Beams
+==============
+
+pyuvdata defines several analytic primary beams for radio telescopes. While these
+are not realistic models for true antennas (like those represented in
+:class:`pyuvdata.UVBeam`), they can be useful in simulation because they are
+lightweight and fast to evaluate (as opposed to having to interpolate).
+
+The analytic beams defined in pyuvdata are based on an abstract base class,
+:class:`pyuvdata.analytic_beam.AnalyticBeam`, which ensures a standard interface
+and can be used to define other analytic beams in a consistent way. To evaluate
+analytic beams in particular directions at particular frequencies, use the
+:meth:`pyuvdata.analytic_beam.AnalyticBeam.efield_eval` or
+:meth:`pyuvdata.analytic_beam.AnalyticBeam.power_eval` methods as appropriate.
+
+The ``AnalyticBeam`` base class also provides a yaml constructor that can enable
+analytic beams to be instantiated directly from yaml files (see
+:ref:`yaml_constructors`, similar constructors are also available for UVBeam
+objects) and a plugin infrastructure that can automatically include any imported
+subclass even if they are defined in other packages. This infrastructure, along
+with the :class:`pyuvdata.BeamInterface` class, can simplify the setup for
+simulations.
+
+.. autoclass:: pyuvdata.analytic_beam.AnalyticBeam
+   :members:
+
+
+.. autoclass:: pyuvdata.AiryBeam
+   :members:
+
+.. autoclass:: pyuvdata.GaussianBeam
+   :members:
+
+.. autoclass:: pyuvdata.ShortDipoleBeam
+   :members:
+
+.. autoclass:: pyuvdata.UniformBeam
+   :members:
+
+
+.. _yaml_constructors:
+
+yaml constructors
+-----------------
+
+Analytic beams can be instantiated directly from yaml files using the
+``!AnalyticBeam`` tag. The ``class`` parameter must be specified and it can be
+set to one of the pyuvdata provided analytic beams or to any AnalyticBeam
+subclass. If the subclass is not defined in pyuvdata, either the subclass must
+already be imported or it must be specified with the dot-pathed modules included
+(i.e. ``my_module.MyAnalyticBeam``). Some analytic beams have required parameters
+(e.g. ``diameter`` for AiryBeams), which must also be provided, see the object
+definitions for details.
+
+Some examples are provided below, note that the node key can be anything, it
+does not need to be ``beam``:
+
+A 16 meter diameter Airy beam::
+
+    beam: !AnalyticBeam
+        class: AiryBeam
+        diameter: 16
+
+A classical short dipole beam (the dot-pathed module notation is not required
+for pyvudata beams but is shown here as an example)::
+
+    beam: !AnalyticBeam
+        class: pyuvdata.ShortDipoleBeam
+
+A gaussian shaped beam with an E-Field beam sigma of 0.26 radians that has
+width that scales as a power law with frequency::
+
+    beam: !AnalyticBeam
+        class: GaussianBeam
+        reference_frequency: 120000000.
+        spectral_index: -1.5
+        sigma: 0.26

docs/beam_interface.rst

@@ -0,0 +1,13 @@
+Beam Interface
+==============
+
+The BeamInterface object is designed to provide a unified interface for UVBeam
+and AnalyticBeam objects to compute beam response values. It can be constructed
+with either a UVBeam or AnalyticBeam and it provides the
+:meth:`pyuvdata.BeamInterface.compute_response` method, which can be used to
+either evaluate the response of an AnalyticBeam or interpolate a UVBeam to get
+the beam response. This interface provides a simplified way for simulators to
+call either UVBeams or analytic beams.
+
+.. autoclass:: pyuvdata.BeamInterface
+   :members:

docs/cst_settings_yaml.rst

@@ -7,8 +7,7 @@ via keywords when the files are read in, but it is better for the metadata to be
 specified once and carried with the data files. To that end, we developed a yaml
 settings file specification to carry all the metadata. This format is very human
 readable and writeable and we encourage using such a file as the best way to
-ensure the metadata is preserved. Note that reading a yaml settings file into
-UVBeam requires that pyyaml is installed.
+ensure the metadata is preserved.
 
 Required Fields
 ***************

docs/make_index.py

@@ -49,6 +49,8 @@ def write_index_rst(readme_file=None, write_file=None):
         "   uvbeam\n"
         "   uvflag\n"
         "   telescope\n"
+        "   analytic_beams\n"
+        "   beam_interface\n"
         "   fast_uvh5_meta\n"
         "   fast_calh5_meta\n"
         "   utility_functions\n"

docs/make_uvbeam.py

@@ -21,7 +21,9 @@ def write_uvbeam_rst(write_file=None):
         "transforming the data (interpolating/regridding, selecting, converting\n"
         "types) and can be interacted with directly.\n\n"
         "Note that there are some tricks that can help with reading in CST beam\n"
-        "simulation files in `CST Settings Files`_.\n\n"
+        "simulation files in `CST Settings Files`_.\n"
+        "UVBeam also provides a yaml constructor that can enable beams to be\n"
+        "instantiated directly from yaml files (see: `UVbeam yaml constructor`_)\n\n"
         "Attributes\n----------\n"
         "The attributes on UVBeam hold all of the metadata and data required to\n"
         "describe primary beam models. Under the hood, the attributes are implemented\n"
@@ -67,6 +69,33 @@ def write_uvbeam_rst(write_file=None):
 
     out += "Methods\n-------\n.. autoclass:: pyuvdata.UVBeam\n  :members:\n\n"
 
+    out += """
+UVBeam yaml constructor
+-----------------------
+
+UVbeams can be instantiated directly from yaml files using the
+``!UVBeam`` tag. The ``filename`` parameter must be specified and and
+any other parameter that can be passed to the :meth:`pyuvdata.UVBeam.read`
+method can also be specified.
+
+Some examples are provided below, note that the node key can be anything,
+it does not need to be ``beam``:
+
+A simple UVBeam specification::
+
+    beam: !UVBeam
+        filename: hera.beamfits
+
+An UVbeam specification with some with some keywords to pass to ``UVBeam.read``::
+
+    beam: !UVBeam
+        filename: mwa_full_EE_test.h5
+        pixels_per_deg: 1
+        freq_range: [100.e+6, 200.e+6]
+
+\n\n
+"""
+
     with open("cst_settings_yaml.rst", encoding="utf-8") as cst_settings_file:
         cst_setting_text = cst_settings_file.read()
 

docs/uvcal_tutorial.rst

@@ -324,6 +324,7 @@ that should be noted:
   on the object itself).
 * Regardless of the value of ``undo``, the convention that is inferred for the
   calibration solutions is determined as follows:
+
   * If neither ``uvc_pol_convention`` nor ``uvcal.pol_convention`` are specified, a
     a warning is raised (since the resulting calibrated data is not well-determined),
     and it is *assumed* that the solutions have the same convention as the ``UVData``
@@ -332,7 +333,9 @@ that should be noted:
     corrections are applied, and the result is ambiguous.
   * If both ``uvc_pol_convention`` and ``uvcal.pol_convention`` are specified and are
     different, an error is raised.
+
 * When **calibrating** in :func:`pyuvdata.utils.uvcalibrate` (i.e. ``undo=False``):
+
   * If ``uvdata.pol_convention`` is specified, an error is raised, because you are
     trying to calibrate already-calibrated data.
   * The convention applied to the resulting ``UVData`` object is inferred in the
@@ -341,14 +344,17 @@ that should be noted:
     or ``uvcal.pol_convention``, see above), (iii) if still unspecified, no convention
     will be used and a warning will be raised. This was always the behaviour in earlier
     versions of ``pyuvdata`` (pre-v3).
+
 * When **un-calibrating** with :func:`pyuvdata.utils.uvcalibrate` (i.e. ``undo=True``):
+
   * If both ``uvd_pol_convention`` and ``uvdata.pol_convention`` are defined and
     are different, an error is raised.
   * If neither are set, a warning is raised, since the resulting un-calibrated values
     may not be the same as the original values before calibration (since a different
     convention could have been used to calibrate originally than is being used to
     de-calibrate). However, calibration will continue, assuming that the ``UVData``
     object has the same convention as the ``UVCal`` object used to de-calibrate.
+
 * It is not supported to have ``pol_convention`` set on ``UVCal``, but *not*
   ``gain_scale``. A ``pol_convention`` only makes sense in the context of having a
   scale for the gains.