update documentation

docs/source/index.rst

@@ -12,7 +12,7 @@ a-flyin’ <https://youtu.be/qKxgfnoz2pk>`_
 ``maria`` simulates celestial observations by ground-based millimeter- and submillimeter-wave arrays like `ALMA <https://en.wikipedia.org/wiki/Atacama_Large_Millimeter_Array>`_, `AtLAST <https://www.atlast.uio.no/>`_, and `MUSTANG-2 <https://greenbankobservatory.org/science/gbt-observers/mustang-2/>`_.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    installation.rst
    usage.rst

docs/source/usage.rst

@@ -3,14 +3,10 @@ Usage
 =====
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
-   simulations.rst
-   instruments.rst
-   sites.rst
-   plans.rst
-   atmosphere.rst
-   cmb.rst
-   maps.rst
-   noise.rst
-   mapping.rst
+   usage/instruments.rst
+   usage/sites.rst
+   usage/plans.rst
+   usage/simulations.rst
+   usage/mapping.rst

docs/source/usage/instruments.rst

@@ -0,0 +1,11 @@
+===========
+Instruments
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+   instruments/index.rst
+   instruments/bands.rst
+   instruments/arrays.rst
+   instruments/noise.rst

docs/source/usage/instruments/arrays.rst

@@ -0,0 +1,39 @@
+
+######
+Arrays
+######
+
+To customize an array, we specify a field of view and add some `Band`.
+
+.. code-block:: python
+
+    array = {"primary_size": 10 # in meters
+             "field_of_view": 0.5 # in degrees
+             "bands": [my_band],
+             }
+
+When passed to `Instrument`, this will generate an array such that the beams do not overlap and fill up the field of view.
+Instead of a `Band`, we can also pass a string that names a pre-defined band, or a mixture of the two.
+
+.. code-block:: python
+
+    array = {"primary_size": 10 # in meters
+             "field_of_view": 0.5 # in degrees
+             "bands": [my_band, "mustang2/f093"],
+             }
+
+Constructing an `Instrument` is then done as
+
+.. code-block:: python
+
+    instrument = maria.get_instrument(array=array)
+
+To construct an instrument with multiple subarrays, we can create a `dict` wherein each value is a valid array:
+
+
+.. code-block:: python
+
+    subarrays = {"array1": {"array_offset": (0.1, 0), "field_of_view": 0.05, "bands": [f150]},
+                "array2": {"array_offset": (-0.1, 0), "field_of_view": 0.05, "bands": [f150]},}
+
+    instrument = maria.get_instrument(subarrays=subarrays)

docs/source/usage/instruments/bands.rst

@@ -0,0 +1,13 @@
+#####
+Bands
+#####
+
+.. code-block:: python
+
+    from maria.instrument import Band
+
+    my_band = Band(center=150, # in GHz
+                   width=30, # in GHz
+                   efficiency=0.5
+                   sensitivity=1e-5
+                   )

docs/source/usage/instruments/index.rst

@@ -0,0 +1,24 @@
+########
+Overview
+########
+
+The observing instrument is instantiated as an ``Instrument``.
+The simplest way to get an instrument is to grab a pre-defined one, e.g.:
+
+.. code-block:: python
+
+    # The Atacama Cosmology Telescope
+    act = maria.get_instrument('ACT')
+
+    # The Atacama Large Millimeter Array
+    alma = maria.get_instrument('ALMA')
+
+    # MUSTANG-2
+    m2 = maria.get_instrument('MUSTANG-2')
+
+
+To see the list of supported instruments, run
+
+.. code-block:: python
+
+    print(maria.all_instruments)

docs/source/usage/instruments/noise.rst

@@ -0,0 +1,32 @@
+#####
+Noise
+#####
+
+Noise is specified for a given band
+
+.. code-block:: python
+
+    band_with_noise = Band(center=150,
+                           width=30,
+                           sensitivity=5e-5,
+                           knee=1e0,
+                           gain_error=1e-1)
+
+We can also use the
+
+.. code-block:: python
+
+    band_with_noise = Band(center=150,
+                           width=30,
+                           sensitivity=5e-5,
+                           knee=1e0,
+                           gain_error=1e-1)
+
+
+Note that any sensitivity units are only implicit due to the imperfect efficiency (caused by the instrument and the atmosphere).
+For a heuristic, the band implicitly assumes that we are observing the zenith at the ALMA site with a PWV of 1mm, and converts the given sensitivity to the corresponding noise equivalent power.
+We can customize this by setting the sensitivity as
+
+.. code-block:: python
+
+    my_band.set_sensitivity(1e-5, pwv=2, elevation=45, region="mauna_kea")

docs/source/usage/mapping.rst

@@ -0,0 +1,36 @@
+#######
+Mapping
+#######
+
+We can map a ``TOD`` (or several of them) with a ``Mapper``. The simplest possible mapper just bins the data:
+
+.. code-block:: python
+
+    from maria.map.mappers import BinMapper
+
+    mapper = BinMapper(center=(150, 10),
+                       frame="ra_dec",
+                       width=1e0,
+                       height=1e0,
+                       resolution=5e-3,
+                       tod_preprocessing={
+                            "window": {"tukey": {"alpha": 0.1}},
+                            "remove_modes": {"n": 1},
+                            "filter": {"f_lower": 0.01},
+                            "despline": {"knot_spacing": 5},
+                                        },
+                        map_postprocessing={
+                            "gaussian_filter": {"sigma": 1},
+                            "median_filter": {"size": 1},
+                                        },
+                       units="K_RJ",
+                       tods=[tod],
+                       )
+
+    output_map = mapper.run()
+
+where we define the preprocessing to be done on the ``TOD``. We can see the output with
+
+.. code-block:: python
+
+    output_map.plot()