large restructuring of intro text and API into folder.

docs/api/analysis.md

@@ -0,0 +1,6 @@
+# Analysis
+
+```{eval-rst}
+.. automodule:: mpol.onedim
+    :members:
+```

docs/api/coordinates.md

@@ -0,0 +1,6 @@
+# Coordinates
+
+```{eval-rst}
+.. automodule:: mpol.coordinates
+    :members:
+```

docs/api/crossval.md

@@ -0,0 +1,6 @@
+# Cross-validation
+
+```{eval-rst}
+.. automodule:: mpol.crossval
+    :members:
+```

docs/api/datasets.md

@@ -0,0 +1,6 @@
+# Datasets
+
+```{eval-rst}
+.. automodule:: mpol.datasets
+    :members:
+```

docs/api/fourier.md

@@ -0,0 +1,6 @@
+# Fourier
+
+```{eval-rst}
+.. automodule:: mpol.fourier
+    :members:
+```

docs/api/geometry.md

@@ -0,0 +1,6 @@
+# Geometry
+
+```{eval-rst}
+.. automodule:: mpol.geometry
+    :members:
+```

docs/api/gridding.md

@@ -0,0 +1,6 @@
+# Gridding
+
+```{eval-rst}
+.. automodule:: mpol.gridding
+    :members:
+```

docs/api/images.md

@@ -0,0 +1,6 @@
+# Images
+
+```{eval-rst}
+.. automodule:: mpol.images
+    :members:
+```

docs/api/plotting.md

@@ -0,0 +1,6 @@
+# Plotting
+
+```{eval-rst}
+.. automodule:: mpol.plot
+    :members:
+```

docs/api/precomposed.md

@@ -0,0 +1,8 @@
+# Precomposed Modules
+
+For convenience, we provide some "precomposed" [modules](https://pytorch.org/docs/stable/notes/modules.html) which may be useful for simple imaging or modeling applications. In general, though, we encourage you to compose your own set of layers if your application requires it. The source code for a precomposed network can provide useful a starting point. We also recommend checking out the PyTorch documentation on [modules](https://pytorch.org/docs/stable/notes/modules.html).
+
+```{eval-rst}
+.. automodule:: mpol.precomposed
+    :members:
+```

docs/api/train_test.md

@@ -0,0 +1,6 @@
+# Training and testing
+
+```{eval-rst}
+.. automodule:: mpol.training
+    :members:
+```

docs/api/utilities.md

@@ -0,0 +1,6 @@
+# Utilities
+
+```{eval-rst}
+.. automodule:: mpol.utils
+    :members:
+```

docs/background.md

@@ -0,0 +1,42 @@
+# Background and prerequisites
+
+## Radio astronomy
+
+A background in radio astronomy, Fourier transforms, and interferometry is a prerequisite for using MPoL but is beyond the scope of this documentation. We recommend reviewing these resources as needed.
+
+- [Essential radio astronomy](https://www.cv.nrao.edu/~sransom/web/xxx.html) textbook by James Condon and Scott Ransom, and in particular, Chapter 3.7 on Radio Interferometry.
+- NRAO's [17th Synthesis Imaging Workshop](http://www.cvent.com/events/virtual-17th-synthesis-imaging-workshop/agenda-0d59eb6cd1474978bce811194b2ff961.aspx) recorded lectures and slides available
+- [Interferometry and Synthesis in Radio Astronomy](https://ui.adsabs.harvard.edu/abs/2017isra.book.....T/abstract) by Thompson, Moran, and Swenson. An excellent and comprehensive reference on all things interferometry.
+- The [Revisiting the radio interferometer measurement equation](https://ui.adsabs.harvard.edu/abs/2011A%26A...527A.106S/abstract) series by O. Smirnov, 2011
+- Ian Czekala's lecture notes on [Radio Interferometry and Imaging](https://iancze.github.io/courses/as5003/lectures/)
+
+RML imaging is different from CLEAN imaging, which operates as a deconvolution procedure in the image plane. However, CLEAN is by far the dominant algorithm used to synthesize images from interferometric data at sub-mm and radio wavelengths, and it is useful to have at least a basic understanding of how it works. We recommend
+
+- [Interferometry and Synthesis in Radio Astronomy](https://ui.adsabs.harvard.edu/abs/2017isra.book.....T/abstract) Chapter 11.1
+- David Wilner's lecture on [Imaging and Deconvolution in Radio Astronomy](https://www.youtube.com/watch?v=mRUZ9eckHZg)
+- For a discussion on using both CLEAN and RML techniques to robustly interpret kinematic data of protoplanetary disks, see Section 3 of [Visualizing the Kinematics of Planet Formation](https://ui.adsabs.harvard.edu/abs/2020arXiv200904345D/abstract) by The Disk Dynamics Collaboration
+
+## Statistics and Machine Learning
+
+MPoL is built on top of the [PyTorch](https://pytorch.org/) machine learning framework and adopts much of the terminology and design principles of machine learning workflows. As a prerequisite, we recommend at least a basic understanding of statistics and machine learning principles. Two excellent (free) textbooks are
+
+- [Dive into Deep Learning](https://d2l.ai/), in particular chapters 1 - 3 to cover the basics of forward models, automatic differentiation, and optimization.
+- [Deep Learning: Foundations and Concepts](https://www.bishopbook.com/) for a lengthier discussion of these concepts and other foundational statistical concepts.
+
+And we highly recommend the informative and entertaining 3b1b lectures on [deep learning](https://www.youtube.com/watch?v=aircAruvnKk&list=PLZHQObOWTQDNU6R1_67000Dx_ZCJB-3pi&ab_channel=3Blue1Brown).
+
+## PyTorch
+
+As a PyTorch library, MPoL expects that the user will write Python code that uses MPoL primitives as building blocks to solve their interferometric imaging workflow, much the same way the artificial intelligence community writes Python code that uses PyTorch layers to implement new neural network architectures (for [example](https://github.com/pytorch/examples)). You will find MPoL easiest to use if you follow PyTorch customs and idioms, e.g., feed-forward neural networks, data storage, GPU acceleration, and train/test optimization loops. Therefore, a basic familiarity with PyTorch is considered a prerequisite for MPoL.
+
+If you are new to PyTorch, we recommend starting with the official [Learn the Basics](https://pytorch.org/tutorials/beginner/basics/intro.html) guide. You can also find high quality introductions on YouTube and in textbooks.
+
+## RML Imaging
+
+MPoL is a modern PyTorch imaging library, however many of the key concepts behind Regularized Maximum Likelihood image have been around for some time. We recommend checking out the following (non-exhaustive) list of resources
+
+- [Regularized Maximum Likelihood Image Synthesis and Validation for ALMA Continuum Observations of Protoplanetary Disks](https://ui.adsabs.harvard.edu/abs/2023PASP..135f4503Z/abstract) by Zawadzki et al. 2023
+- The fourth paper in the 2019 [Event Horizon Telescope Collaboration series](https://ui.adsabs.harvard.edu/abs/2019ApJ...875L...4E/abstract) describing the imaging principles
+- [Maximum entropy image restoration in astronomy](https://ui.adsabs.harvard.edu/abs/1986ARA%26A..24..127N/abstract) AR&A by Narayan and Nityananda 1986
+- [Multi-GPU maximum entropy image synthesis for radio astronomy](https://ui.adsabs.harvard.edu/abs/2018A%26C....22...16C/abstract) by Cárcamo et al. 2018
+- Dr. Katie Bouman's Ph.D. thesis ["Extreme Imaging via Physical Model Inversion: Seeing Around Corners and Imaging Black Holes"](https://people.csail.mit.edu/klbouman/pw/papers_and_presentations/thesis.pdf)

docs/developer-documentation.md

@@ -18,8 +18,6 @@ Extra packages required for development can be installed via
 
 This directs pip to install whatever package is in the current working directory (`.`) as an editable package (`-e`), using the set of `[dev]` optional packages. There is also a more limited set of packages under `[test]`. You can view these packages in the `pyproject.toml` file. 
 
-
-(testing-reference-label)=
 ## Testing
 
 MPoL includes a test suite written using [pytest](https://docs.pytest.org/). We aim for this test suite to be as comprehensive as possible, since this helps us achieve our goal of shipping stable software.

docs/index.md

@@ -9,7 +9,7 @@ As a PyTorch *library*, MPoL expects that the user will write Python code to lin
 
 MPoL is *not* an imaging application nor a pipeline, though MPoL components could be used to build specialized workflows. We are focused on providing a numerically correct and expressive set of core primitives so the user can leverage the full power of the PyTorch (and Python) ecosystem to solve their research-grade imaging tasks. This is already a significant development and maintenance burden for the limited resources of our small research team, so our immediate scope must necessarily be limited.
 
-To get a sense of what MPoL is and what background material this library assumes, please look at the [](introduction.md). If the package is right for your needs, follow the [installation instructions](installation.md).
+To get a sense of what background material MPoL assumes, please look at the [](background.md). If the package is right for your needs, follow the [installation instructions](installation.md).
 
 This documentation covers the API and a short set of tutorials demonstrating key components of the MPoL library. Longer examples demonstrating how one might use MPoL components to build an imaging workflow are packaged together in the [MPoL-dev/examples](https://github.com/MPoL-dev/examples) repository.
 
@@ -21,8 +21,8 @@ If you'd like to help build the MPoL package, please check out the [](developer-
 :caption: User Guide
 :maxdepth: 2
 
-introduction.md
-installation.md
+background
+installation
 ci-tutorials/PyTorch
 ci-tutorials/gridder
 ci-tutorials/optimization

docs/installation.md

@@ -1,6 +1,6 @@
 # MPoL Installation
 
-MPoL requires `python >= 3.8`.
+MPoL requires `python >= 3.10`.
 
 ## Using pip
 
@@ -16,8 +16,6 @@ Or if you require a specific version of MPoL (e.g., `0.2.0`), you can install vi
 $ pip install MPoL==0.2.0
 ```
 
-We recommend that you install the latest version of MPoL. Though, if you are working on a project across several compute environments, you may wish to ensure that each environment has the same version of MPoL installed.
-
 ## From source
 
 If you'd like to install the package from source to access the latest development version, download or `git clone` the MPoL repository and install
@@ -30,7 +28,7 @@ $ pip install .
 
 If you have trouble installing please raise a [github issue](https://github.com/MPoL-dev/MPoL/issues) with the particulars of your system.
 
-If you're interested in contributing to the MPoL package, please see the {ref}`developer-documentation-label`.
+If you're interested in contributing to the MPoL package, please see the [](developer-documentation.md).
 
 ## Upgrading
 
@@ -60,10 +58,4 @@ $ python
 
 The documentation served online ([here](https://mpol-dev.github.io/MPoL/index.html)) corresponds to the `main` branch. This represents the current state of MPoL and is usually the best place to reference MPoL functionality. However, this documentation may be more current than last tagged version or the version you have installed. If you require the new features detailed in the documentation, then we recommend installing the package from source (as above).
 
-In the (foreseeably rare) situation where the latest online documentation significantly diverges from the package version you wish to use (but there are reasons you do not want to build the `main` branch from source), you can access the documentation for that version by {ref}`building and viewing the documentation locally <documentation-build-reference-label>`. To do so, clone the repository as above, checkout the version tag, and build the docs locally.
-
-## Using CUDA acceleration
-
-MPoL uses PyTorch for its Neural Networks as seen in the `Optimization Loop` tutorial. If you are interested in using PyTorch's full potential by utilizing a Nvidia graphics card, then the CUDA tool kit will need to be installed (TensorVision is also required). More information on this is available in the `GPU Tutorial` page. It is worth noting that PyTorch may need to be (re)installed separately using a specific `pip` for your system.
-
-More information on this can be found on the PyTorch homepage: [pytorch.org](https://pytorch.org/).
+In the (foreseeably rare) situation where the latest online documentation significantly diverges from the package version you wish to use (but there are reasons you do not want to build the `main` branch from source), you can access the documentation for that version by [building the older documentation locally](developer-documentation.md#older-documentation-versions)