Merge branch 'docs'

docs/_static/css/lentil.css

@@ -100,6 +100,26 @@ dt:target, span.highlighted {
     margin:-80px 0 0; 
 } 
 
+/* Adjust admonition colors */
+.admonition {
+    --pst-color-info: #5E81AC;
+    --pst-color-info-bg: #E5E9F0;
+    --pst-color-warning: #ee9040;
+    --pst-color-warning-bg: #fcf4ee;
+}
+
+/* Style See Also admonition like Info admonition */
+.admonition.seealso, div.admonition.seealso {
+    border-color: #5E81AC;
+}
+.admonition.seealso>.admonition-title::before, div.admonition.seealso>.admonition-title::before {
+    background-color: #E5E9F0;
+}
+.admonition.seealso>.admonition-title::after, div.admonition.seealso>.admonition-title::after {
+    content: var(--pst-icon-admonition-note);
+    color: #5E81AC;
+}
+
 .bd-header {
     --pst-color-primary: #5E81AC;
     --pst-color-link-hover: #5E81AC;

docs/_templates/index.html

@@ -42,7 +42,7 @@ <h1>Lentil: Fast optical propagation</h1>
     <div class="biglinks container py-5 text-center w-75">
         <div class="row gx-5">
             <div class="col-3">
-                <a href="{{ pathto("user/install") }}">
+                <a href="{{ pathto("user/getting_started/install") }}">
                     <img src="_static/installation.svg"><br/>
                     Installation
                 </a>

docs/conf.py

@@ -106,6 +106,18 @@
 
 autosummary_generate = True
 
+rst_prolog = """
+.. currentmodule:: lentil
+
+.. |Pupil| replace:: :class:`Pupil`
+.. |Image| replace:: :class:`Image`
+.. |Detector| replace:: :class:`Detector`
+.. |Plane| replace:: :class:`Plane`
+.. |Wavefront| replace:: :class:`Wavefront`
+.. |Tilt| replace:: :class:`Tilt`
+
+"""
+
 # -- Plot config -------------------------------------------------------------
 dpi = 144
 

docs/docs.rst

@@ -16,7 +16,7 @@ Lentil Documentation
 **Version**: |version|
 
 **Useful links**:
-:doc:`Installation <user/install>` |
+:ref:`user.install` |
 `Source Repository <https://github.com/andykee/lentil>`_ |
 `Issue Tracker <https://github.com/andykee/lentil/issues>`_ |
 
@@ -30,7 +30,7 @@ functions of segmented aperture telescopes.
     Lentil is under active development and new features continue to be added. 
     Until Lentil reaches version 1.0, the API is not guaranteed to be stable, but
     changes breaking backwards compatibility will be noted in the 
-    :doc:`release notes <release>`.
+    :ref:`release notes <release>`.
 
 .. grid:: 2
     :gutter: 5
@@ -52,7 +52,7 @@ functions of segmented aperture telescopes.
 
     .. grid-item-card:: :octicon:`file-code;1em;` Examples
 
-        A number of end-to-end examples and large collection of common
+        End-to-end examples and larger collection of common
         model patterns are provided to simplify the development of new
         models.
 

docs/examples/index.rst

@@ -4,15 +4,30 @@
 Examples
 ********
 
-General
-=======
+This page contains examples and useful model design patterns.
+
 .. toctree::
+    :caption: End-to-end
     :maxdepth: 1
 
     general/simple
     general/large
     general/attributes
 
+.. toctree::
+    :caption: Model patterns
+    :maxdepth: 1
+
+    planes/filter_wheel
+    planes/rb_element
+    planes/translation_stage
+
+.. toctree::
+    :caption: MATLAB
+    :maxdepth: 1
+
+    matlab/matlab_interface
+
 Integration
 ===========
 
@@ -38,9 +53,4 @@ Radiometry
     radiometry/complex_sources
     radiometry/source_defocus
 
-MATLAB
-======
-.. toctree::
-    :maxdepth: 1
 
-    matlab/matlab_interface

docs/ref/detector.rst

@@ -10,7 +10,7 @@ Charge collection
     :toctree: generated/
 
     lentil.detector.collect_charge
-    lentil.detector.collect_charge
+    lentil.detector.collect_charge_bayer
 
 Pixel effects
 -------------

docs/ref/internals.rst

@@ -4,6 +4,13 @@
 Internals
 *********
 
+Plane type
+----------
+.. autosummary::
+    :toctree: generated/
+
+    lentil.ptype.ptype
+
 Field
 -----
 .. autosummary::

docs/user/advanced/extend.rst

@@ -0,0 +1,120 @@
+.. _user.advanced.extend:
+
+****************
+Extending Lentil
+****************
+
+Customizing Plane
+=================
+The Plane class or any of the classes derived from Plane can be subclassed to modify
+any of the default behavior. Reasons to do this may include but are not limited to:
+
+* Dynamically computing the :attr:`~lentil.Plane.opd` attribute
+* Changing the Plane-Wavefront interaction by redefining the `Plane.multiply()` method
+* Modifying the way a Plane is resampled or rescaled
+
+Some general guidance for how to safely subclass Plane is provided below.
+
+.. note::
+
+    Lentil's |Plane| class and its subclasses all use Python's ``__init_subclass__()``
+    method to ensure any required default values are set - even if a user-defined
+    subclass does not explicitly call ``Plane``'s constructor ``__init__()`` method. For
+    this reason, it is not strictly necessary to call ``super().__init__()`` when
+    implementing a custom Plane subclass. It also won't hurt, as long as you're careful
+    to either call ``super().__init__()`` before defining any static plane attributes or
+    passing these attributes along to the ``super().__init__()`` call to ensure they are
+    properly set.
+
+Redefining the amplitude, OPD, or mask attributes
+---------------------------------------------------
+Plane :attr:`~lentil.Plane.amplitude`, :attr:`~lentil.Plane.opd`, and
+:attr:`~lentil.Plane.mask` are all defined as properties, but Python allows you to
+redefine them as class attributes without issue:
+
+.. code-block:: python3
+
+    import lentil
+
+    class CustomPlane(le.Plane):
+        def __init__(self):
+            self.amplitude = lentil.circle((256,256), 128)
+            self.opd = lentil.zernike(lentil.circlemask((256,256),128), 4)
+
+If more dynamic behavior is required, the property can be redefined. For example, to
+return a new random OPD each time the :attr:`~lentil.Plane.opd` attribute is
+accessed:
+
+.. code-block:: python3
+
+    import numpy as np
+    import lentil
+
+    class CustomPlane(lentil.Plane):
+        def __init__(self):
+            self.mask = lentil.circlemask((256,256), 128)
+            self.amplitude = lentil.circle((256,256), 128)
+
+        @property
+        def phaopdse(self):
+            return lentil.zernike_compose(self.mask, np.random.random(10))
+
+It is also straightforward to implement a custom :attr:`~lentil.Plane.opd` property to
+provide a stateful OPD attribute:
+
+.. code-block:: python3
+
+    import numpy as np
+    import lentil
+
+    class CustomPlane(lentil.Plane):
+        def __init__(self, x=np.zeros(10)):
+            self.mask = lentil.circlemask((256,256), 128)
+            self.amplitude = lentil.circle((256,256), 128)
+            self.x = x
+
+        @property
+        def opd(self):
+            return lentil.zernike_compose(self.mask, self.x)
+
+.. note::
+
+    Polychromatic or broadband diffraction propagations access the OPD, amplitude,
+    and mask attributes for each propagatioon wavelength. Because these attributes
+    remain fixed during a propagation, it is inefficient to repeatedly recompute
+    them. To mitigate this, it can be very useful to provide a mechanism for freezing
+    these dynamic attributes. There are many ways to do this. One approach is provided
+    below:
+
+    .. code-block:: python3
+
+        import copy
+        import numpy as np
+        import lentil
+
+        class CustomPlane(lentil.Plane):
+            def __init__(self):
+                self.mask = lentil.circlemask((256,256), 128)
+                self.amplitude = lentil.circle((256,256), 128)
+
+            @property
+            def opd(self):
+                return lentil.zernike_compose(self.mask, np.random.random(10))
+
+            def freeze(self):
+                # Return a copy of CustomPlane with the OPD attribute redefined
+                # to be a static copy of the OPD when freeze() is called
+                out = copy.deepcopy(self)
+                out.opd = self.opd.copy()
+                return out
+
+
+Customizing Plane methods
+-------------------------
+Any of the |Plane| methods can be redefined in a subclass without restriction. Care
+should be taken to ensure any redefined methods return data compatible with the
+parent method's return type to preserve compatibility within Lentil.
+
+
+Implementing the _Tilt interface
+--------------------------------

docs/user/matlab.rst → docs/user/advanced/matlab.rst

@@ -1,4 +1,4 @@
-.. _user.matlab:
+.. _user.advanced.matlab:
 
 ************************
 Using Lentil with MATLAB