From b79739480b66c7761d954fe5fed484ce6a01c83d Mon Sep 17 00:00:00 2001 From: Andy Kee Date: Thu, 25 Jan 2024 07:01:22 -0800 Subject: [PATCH] Docs cleanup --- docs/dev/install.rst | 7 +- docs/dev/publishing.rst | 2 +- docs/user/fundamentals/apertures.rst | 4 +- docs/user/fundamentals/planes.rst | 261 +++++++++++---------- docs/user/fundamentals/tilt.rst | 16 +- docs/user/fundamentals/wavefront_error.rst | 2 +- docs/user/getting_started/install.rst | 14 +- 7 files changed, 158 insertions(+), 148 deletions(-) diff --git a/docs/dev/install.rst b/docs/dev/install.rst index aa50397..89856e8 100644 --- a/docs/dev/install.rst +++ b/docs/dev/install.rst @@ -7,13 +7,14 @@ Install Lentil for development Forking the Lentil repo ======================= -Matplotlib is hosted at `andykee/lentil.git `_. +Lentil is hosted at `andykee/lentil.git `_. If you plan on solving issues or submitting pull requests to the main Lentil repository, you should first fork this repository by visiting `andykee/lentil.git `_ and clicking on the ``Fork`` button on the top right of the page. See the -`GitHub documentation `_ -for more details. +`GitHub documentation +`_ for more +details. Installing from source ====================== diff --git a/docs/dev/publishing.rst b/docs/dev/publishing.rst index 893471c..a77aad3 100644 --- a/docs/dev/publishing.rst +++ b/docs/dev/publishing.rst @@ -28,4 +28,4 @@ Upload the release .. note:: - Only core-team members are able to publish new releases to PyPi. + Only core dev team members are able to publish new releases to PyPi. diff --git a/docs/user/fundamentals/apertures.rst b/docs/user/fundamentals/apertures.rst index 245d833..79dcfa5 100644 --- a/docs/user/fundamentals/apertures.rst +++ b/docs/user/fundamentals/apertures.rst @@ -13,8 +13,8 @@ Aperture or mask shapes can be loaded from a file, created manually, or constructed using one or more of Lentil's functions for drawing common shapes in an array. -Core shapes -=========== +Basic shapes +============ Lentil provides a number of functions for drawing basic shapes in arrays. Multiple arrays can be combined to create more complicated shapes. diff --git a/docs/user/fundamentals/planes.rst b/docs/user/fundamentals/planes.rst index 417f90a..7f0cb1d 100644 --- a/docs/user/fundamentals/planes.rst +++ b/docs/user/fundamentals/planes.rst @@ -4,74 +4,55 @@ Planes ****** -All Lentil planes are derived from the |Plane| class. This base class defines the -interface to represent any discretely sampled plane in an optical model. Planes -typically have some influence on the propagation of a wavefront though this is -not strictly required and models may use *dummy* or *reference* planes as needed. +All Lentil planes are derived from the |Plane| class. This base class defines +the interface to represent any discretely sampled plane in an optical model. +Planes typically have some influence on the propagation of a wavefront though +this is not strictly required and models may use *dummy* or *reference* planes +as needed. -Lentil provides several general planes that are the building blocks for most optical -models: +Lentil provides several general planes that are the building blocks for most +optical models: * The |Plane| base class provides the core logic for representing and working with discretely sampled planes in an optical model. * The |Pupil| plane provides a convenient way to represent a pupil plane - in an optical system. There is nothing particularly special about pupil planes, they - merely provide a convenient location (mathematically-speaking) to enforce limiting - apertures or stops and include optical aberrations. More detailed discussion of pupil - planes is available in [1]_. + in an optical system. There is nothing particularly special about pupil + planes, they merely provide a convenient location (mathematically-speaking) + to enforce limiting apertures or stops and include optical aberrations. More + detailed discussion of pupil planes is available in [1]_. * The |Image| plane provides a location where the image formed by an optical system may be manipulated or viewed. * The |Detector| plane is conceptually identical to the Image plane but is optimized to very efficiently compute intensity from a complex field. -In addition, several "utility" planes are provided. These planes do not represent -physical components of an optical system, but are used to implement commonly encountered -optical effects: +In addition, several "utility" planes are provided. These planes do not +represent physical components of an optical system, but are used to implement +commonly encountered optical effects: * The |Tilt| plane is used to represent wavefront tilt in terms of radians of x and y tilt. * The :class:`~lentil.Rotate` plane rotates a wavefront by an arbitrary angle. -* The :class:`~lentil.Flip` plane flips a wavefront about its x, y, or both x and y - axes. - -ptype -===== -A plane's type (:attr:`~lentil.Plane.ptype`) defines how it interacts with a -|Wavefront|. When a wavefront interacts with a plane, it inherits the plane's -``ptype``. Plane type is set automatically and unexpected behavior may -occur if it is changed. - -Lentil planes support the following ptypes: - -================== ====================================================== -ptype Planes with this type -================== ====================================================== -:class:`none` :class:`~lentil.Plane` -:class:`pupil` :class:`~lentil.Pupil` -:class:`image` :class:`~lentil.Image`, :class:`~lentil.Detector` -:class:`tilt` :class:`~lentil.Tilt`, :class:`~lentil.DispersiveTilt` -:class:`transform` :class:`~lentil.Rotate`, :class:`~lentil.Flip` -================== ====================================================== - -The rules defining when a wavefront is allowed to interact with a plane based -on ``ptype`` are described :ref:`here `. +* The :class:`~lentil.Flip` plane flips a wavefront about its x, y, or both x + and y axes. Plane ===== -Lentil's |Plane| class represents a discretely sampled plane in an optical model. Planes -have attributes for representing the sampled complex amplitude of the plane as well as -additional metadata that may influence how a propagating wavefront interacts with the -plane. A plane is defined by the following parameters: - -* :attr:`~lentil.Plane.amplitude` - Defines the relative electric field amplitude - transmission through the plane -* :attr:`~lentil.Plane.opd` - Defines the optical path difference that a wavefront - experiences when propagating through the plane -* :attr:`~lentil.Plane.mask` - Defines the binary mask over which the plane data is - valid. If `mask` is 2-dimensional, the plane is assumed to be monolithic. If `mask` - is 3-dimensional, the plane is assumed to be segmented with the individual segment - masks inserted along the first dimension. If mask is not provided, it is automatically - created as needed from the nonzero values in :attr:`~lentil.Plane.amplitude`. +Lentil's |Plane| class represents a discretely sampled plane in an optical +model. Planes have attributes for representing the sampled complex amplitude +of the plane as well as additional metadata that may influence how a +propagating wavefront interacts with the plane. A plane is defined by the +following parameters: + +* :attr:`~lentil.Plane.amplitude` - Defines the relative electric field + amplitude transmission through the plane +* :attr:`~lentil.Plane.opd` - Defines the optical path difference that a + wavefront experiences when propagating through the plane +* :attr:`~lentil.Plane.mask` - Defines the binary mask over which the plane + data is valid. If `mask` is 2-dimensional, the plane is assumed to be + monolithic. If `mask` is 3-dimensional, the plane is assumed to be segmented + with the individual segment masks inserted along the first dimension. If + mask is not provided, it is automatically created as needed from the nonzero + values in :attr:`~lentil.Plane.amplitude`. .. plot:: _img/python/segmask.py :scale: 50 @@ -111,50 +92,75 @@ Once a Plane is defined, its attributes can be modified at any time: Resampling or rescaling a Plane ------------------------------- -It is possible to resample a plane using either the :func:`~lentil.Plane.resample` -or :func:`~lentil.Plane.rescale` methods. Both methods use intrepolation to -resample the amplitude, opd, and mask attributes and readjust the pixelscale -attribute as necessary. +It is possible to resample a plane using either the +:func:`~lentil.Plane.resample` or :func:`~lentil.Plane.rescale` methods. Both +methods use intrepolation to resample the amplitude, opd, and mask attributes +and readjust the pixelscale attribute as necessary. .. _user.planes.pupil: +ptype +===== +A plane's type (:attr:`~lentil.Plane.ptype`) defines how it interacts with a +|Wavefront|. When a wavefront interacts with a plane, it inherits the plane's +``ptype``. Plane type is set automatically and unexpected behavior may +occur if it is changed. + +Lentil planes support the following ptypes: + +================== ====================================================== +ptype Planes with this type +================== ====================================================== +:class:`none` :class:`~lentil.Plane` +:class:`pupil` :class:`~lentil.Pupil` +:class:`image` :class:`~lentil.Image`, :class:`~lentil.Detector` +:class:`tilt` :class:`~lentil.Tilt`, :class:`~lentil.DispersiveTilt` +:class:`transform` :class:`~lentil.Rotate`, :class:`~lentil.Flip` +================== ====================================================== + +The rules defining when a wavefront is allowed to interact with a plane based +on ``ptype`` are described +:ref:`here `. + Pupil ===== -Lentil's |Pupil| class provides a convenient way to represent a generalized pupil -function. |Pupil| planes behave exactly like |Plane| objects but introduce an implied -spherical phase term defined by the :attr:`~lentil.Pupil.focal_length` attribute. The -spherical phase term is opaque to the user but is given by +Lentil's |Pupil| class provides a convenient way to represent a generalized +pupil function. |Pupil| planes behave exactly like |Plane| objects but +introduce an implied spherical phase term defined by the +:attr:`~lentil.Pupil.focal_length` attribute. The spherical phase term is +opaque to the user but is given by .. math:: \frac{1}{2f} \left(x^2 + y^2\right) -where :math:`f` is the focal length and :math:`x` and :math:`y` are pupil plane -coordinates. +where :math:`f` is the focal length and :math:`x` and :math:`y` are pupil +plane coordinates. A pupil is defined by the following required parameters: * :attr:`~lentil.Pupil.focal_length` - The effective focal length (in meters) represented by the pupil -* :attr:`~lentil.Pupil.pixelscale` - Defines the physical sampling of each pixel in - the discretely sampled attributes described below +* :attr:`~lentil.Pupil.pixelscale` - Defines the physical sampling of each + pixel in the discretely sampled attributes described below Discreetly sampled pupil attributes can also be specified: -* :attr:`~lentil.Pupil.amplitude` - Defines the relative electric field amplitude - transmission through the pupil -* :attr:`~lentil.Pupil.opd` - Defines the optical path difference that a wavefront - experiences when propagating through the pupil. -* :attr:`~lentil.Pupil.mask` - Defines the binary mask over which the pupil data is - valid. If `mask` is 2-dimensional, the pupil is assumed to be monolithic. If `mask` - is 3-dimensional, the pupil is assumed to be segmented with the segment masks - allocated along the first dimension. If mask is not provided, it is automatically - created as needed from the nonzero values in :attr:`~lentil.Pupil.amplitude`. +* :attr:`~lentil.Pupil.amplitude` - Defines the relative electric field + amplitude transmission through the pupil +* :attr:`~lentil.Pupil.opd` - Defines the optical path difference that a + wavefront experiences when propagating through the pupil. +* :attr:`~lentil.Pupil.mask` - Defines the binary mask over which the pupil + data is valid. If `mask` is 2-dimensional, the pupil is assumed to be + monolithic. If `mask` is 3-dimensional, the pupil is assumed to be segmented + with the segment masks allocated along the first dimension. If mask is not + provided, it is automatically created as needed from the nonzero values in + :attr:`~lentil.Pupil.amplitude`. .. note:: - All optional Pupil attributes have sensible default values that have no effect on - propagations when not defined. + All optional Pupil attributes have sensible default values that have no + effect on propagations when not defined. Create a pupil with: @@ -164,58 +170,59 @@ Create a pupil with: Image ===== -Lentil's |Image| plane is used to either manipulate or view a wavefront at a focal point -in an optical system. An image plane does not have any required parameters although any -of the following can be specified: - -* :attr:`~lentil.Image.pixelscale` - Defines the physical sampling of each pixel in - the image plane. If not provided, the sampling will be automatically selected to - ensure the results are at least Nyquist sampled. -* :attr:`~lentil.Image.shape` - Defines the shape of the image plane. If not provided, - the image plane will grow as necessary to capture all data. -* :attr:`~lentil.Image.amplitude` - Definers the relative electric field amplitude - transmission through the image plane. -* :attr:`~lentil.Image.opd` - Defines the optical path difference that a wavefront - experiences when propagating through the image plane. +Lentil's |Image| plane is used to either manipulate or view a wavefront at an +image plane in an optical system. An image plane does not have any required +parameters although any of the following can be specified: + +* :attr:`~lentil.Image.pixelscale` - Defines the physical sampling of each + pixel in the image plane. If not provided, the sampling will be + automatically selected to ensure the results are at least Nyquist sampled. +* :attr:`~lentil.Image.shape` - Defines the shape of the image plane. If not + provided, the image plane will grow as necessary to capture all data. +* :attr:`~lentil.Image.amplitude` - Definers the relative electric field + amplitude transmission through the image plane. +* :attr:`~lentil.Image.opd` - Defines the optical path difference that a + wavefront experiences when propagating through the image plane. Detector ======== -Lentil's |Detector| plane is used to accumulate the intensity in an image plane. -Intensity is computed as the absolute value of the complex amplitude in the image plane -squared: +Lentil's |Detector| plane is used to accumulate the intensity in an image +plane. Intensity is computed as the absolute value of the complex amplitude in +the image plane squared: .. math:: \mathbf{I} = \left|\mathbf{W}\right|^2 -Similar to the |Image| plane, a detector plane does not have any required parameters -although any of the following can be specified: +Similar to the |Image| plane, a detector plane does not have any required +parameters although any of the following can be specified: -* :attr:`~lentil.Detector.pixelscale` - Defines the physical sampling of each pixel in - the image plane. If not provided, the sampling will be automatically selected to - ensure the results are at least Nyquist sampled. -* :attr:`~lentil.Detector.shape` - Defines the shape of the image plane. If not provided, - the image plane will grow as necessary to capture all data. +* :attr:`~lentil.Detector.pixelscale` - Defines the physical sampling of each + pixel in the image plane. If not provided, the sampling will be + automatically selected to ensure the results are at least Nyquist sampled. +* :attr:`~lentil.Detector.shape` - Defines the shape of the image plane. If + not provided, the image plane will grow as necessary to capture all data. -While an |Image| plane can be used to compute intensity, the |Detector| plane implements -an algorithm that greatly reduces the memory footprint and increases the speed of this -operation. Details of this algorithm are available in the :ref:`technical-notes`. +While an |Image| plane can be used to compute intensity, the |Detector| plane +implements an algorithm that greatly reduces the memory footprint and +increases the speed of this operation. Details of this algorithm are available +in the :ref:`technical-notes`. .. note:: - An |Image| plane is interchangeable with a |Detector| plane, but the converse is not - true. This is because the calculation of the real-valued intensity discards the complex - field information. Because of this, |Detector| planes can only be used as the final - plane in a Lentil model. + An |Image| plane is interchangeable with a |Detector| plane, but the + converse is not true. This is because the calculation of the real-valued + intensity discards the complex field information. Because of this, + |Detector| planes can only be used as the final plane in a Lentil model. .. _user.planes.tilt: Tilt ==== -The :class:`~lentil.Tilt` plane provides a mechanism for directly specifying wavefront -tilt outside of the context of a discretely sampled |Plane| object. :class:`~lentil.Tilt` -is most useful for representing global tilt in an optical system (for example, due to a -pointing error). +The :class:`~lentil.Tilt` plane provides a mechanism for directly specifying +wavefront tilt outside of the context of a discretely sampled |Plane| object. +:class:`~lentil.Tilt` is most useful for representing global tilt in an +optical system (for example, due to a pointing error). Given the following |Pupil| plane: @@ -230,7 +237,8 @@ Given the following |Pupil| plane: >>> w = lentil.propagate_dft(w, pixelscale=5e-6, shape=(64,64), oversample=2) >>> plt.imshow(w.intensity) -It is simple to see the effect of introducing a tilted wavefront into the system: +It is simple to see the effect of introducing a tilted wavefront into the +system: .. plot:: :include-source: @@ -247,8 +255,8 @@ It is simple to see the effect of introducing a tilted wavefront into the system .. note:: - Notice the use of ``origin='lower'`` in the plot above. For an explanation, see - the note :ref:`here `. + Notice the use of ``origin='lower'`` in the plot above. For an explanation, + see the note :ref:`here `. .. .. _user_guide.planes.transformations: @@ -307,14 +315,15 @@ Grism ----- .. warning:: - :class:`~lentil.Grism` is deprecated and will be removed in a future version. Use - :class:`~lentil.DispersiveTilt` instead. + :class:`~lentil.Grism` is deprecated and will be removed in a future + version. Use :class:`~lentil.DispersiveTilt` instead. -A grism is a combination of a diffraction grating and a prism that creates a dispersed -spectrum normal to the optical axis. This is in contrast to a single grating or prism, -which creates a dispersed spectrum at some angle that deviates from the optical axis. -Grisms are most commonly used to create dispersed spectra for slitless spectroscopy or -to create interference fringes for dispersed fringe sensing. +A grism is a combination of a diffraction grating and a prism that creates a +dispersed spectrum normal to the optical axis. This is in contrast to a single +grating or prism, which creates a dispersed spectrum at some angle that +deviates from the optical axis. Grisms are most commonly used to create +dispersed spectra for slitless spectroscopy or to create interference fringes +for dispersed fringe sensing. Lentil's :class:`~lentil.Grism` plane provides a straightforward mechanism for efficiently modeling a grism. @@ -322,14 +331,14 @@ efficiently modeling a grism. Active optics and deformable mirrors ==================================== -Active optics and deformable mirrors are easily represented by defining an OPD that -depends on some parameterized state. Because there is no standard architecture for these -types of optical elements, Lentil does not provide a concrete implementation. Instead, -a custom subclass of either |Plane| or |Pupil| should be defined. The exact -implementation details will vary by application, but a simple example of a tip-tilt -mirror where the plane's OPD is computed dynamically based on the state `x` is -provided below. Additional examples can be found in Model Patterns under -:ref:`examples.useful_patterns`. +Active optics and deformable mirrors are easily represented by defining an OPD +that depends on some parameterized state. Because there is no standard +architecture for these types of optical elements, Lentil does not provide a +concrete implementation. Instead, a custom subclass of either |Plane| or +|Pupil| should be defined. The exact implementation details will vary by +application, but a simple example of a tip-tilt mirror where the plane's OPD +is computed dynamically based on the state `x` is provided below. Additional +examples can be found in Model Patterns under :ref:`examples.useful_patterns`. .. code-block:: python3 diff --git a/docs/user/fundamentals/tilt.rst b/docs/user/fundamentals/tilt.rst index aa894ff..2d2b1e5 100644 --- a/docs/user/fundamentals/tilt.rst +++ b/docs/user/fundamentals/tilt.rst @@ -1,17 +1,17 @@ .. _user.fundamentals.tilt: -******************************** -Working with large optical tilts -******************************** +**************************************** +Diffraction propagation with large tilts +**************************************** One of lentil's unique features is its hybrid approach to handling tilt. -The plane's :func:`~lentil.Plane.fit_tilt` method performs a least squares fit to -estimate and remove tilt from the :attr:`~lentil.Plane.opd` attribute. The removed -tilt is accounted for by appending an equivalent :class:`~lentil.Tilt` object to the -plane's :attr:`~lentil.Plane.tilt` attribute. The optical effect of the tilt is -automatically applied during a propagation step. +The plane's :func:`~lentil.Plane.fit_tilt` method performs a least squares fit +to estimate and remove tilt from the :attr:`~lentil.Plane.opd` attribute. The +removed tilt is accounted for by appending an equivalent :class:`~lentil.Tilt` +object to the plane's :attr:`~lentil.Plane.tilt` attribute. The optical effect +of the tilt is automatically applied during a propagation step. diff --git a/docs/user/fundamentals/wavefront_error.rst b/docs/user/fundamentals/wavefront_error.rst index ae37812..b8f4122 100644 --- a/docs/user/fundamentals/wavefront_error.rst +++ b/docs/user/fundamentals/wavefront_error.rst @@ -71,7 +71,7 @@ containing the JWST NITCam static wavefront error: >>> import numpy as np >>> import lentil - >>> opd = np.load('path/to/nircam_wfe.npy') + >>> opd = np.load('nircam_wfe.npy') >>> pupil = lentil.Pupil(focal_length=119.77, pixelscale=6.6035/1024, opd=opd) .. image:: /_static/img/nircam.png diff --git a/docs/user/getting_started/install.rst b/docs/user/getting_started/install.rst index 5a68908..22a65ea 100644 --- a/docs/user/getting_started/install.rst +++ b/docs/user/getting_started/install.rst @@ -5,15 +5,15 @@ Installation ************ If you are new to Python and/or do not have familiarity with `Python virtual -environments `_, then we recommend -starting by installing the `Anaconda Distribution -`_. This works on all platforms (linux, -Mac, Windows) and installs a full-featured scientific Python in a user directory -without requiring root permissions. +environments `_, then we +recommend starting by installing the `Anaconda Distribution +`_. This works on all platforms (Linux, +MacOS, Windows) and installs a full-featured scientific Python in a user +directory without requiring root permissions. -Installing ``lentil`` -===================== +Installing Lentil +================= To install using **pip**: .. code-block:: bash