Update docs, tests for v0.7.0

andykee · Mar 8, 2022 · 0eb0231 · 0eb0231
1 parent 21d426d
commit 0eb0231
Show file tree

Hide file tree

Showing 27 changed files with 185 additions and 121 deletions.
diff --git a/docs/_img/python/focus_images.py b/docs/_img/python/focus_images.py
@@ -8,35 +8,39 @@
 amp = np.zeros((256, 256))
 amp += lentil.circlemask((256, 256), 64, shift=(32, 8))
 amp -= lentil.circlemask((256, 256), 40, shift=(32, 8))
-amp[:,0:128+8] = 0
-amp[32:225,104-16:128-16] = 1
+amp[:, 0:128+8] = 0
+amp[32:225, 104-16:128-16] = 1
 amp[96:120, 128-16:144-8] = 1
 amp[201:225, 128-16:144-8] = 1
 
-focus = lentil.zernike(mask=np.ones((256,256)), index=4)
+focus = lentil.zernike(mask=np.ones((256, 256)), index=4)
 
 pupil_neg = lentil.Pupil(amplitude=amp, pixelscale=1/240, focal_length=10)
 pupil_neg.phase = -6e-6 * focus
 w_neg = lentil.Wavefront(650e-9)
 w_neg *= pupil_neg
-w_neg = w_neg.propagate_image(pixelscale=5e-6, npix=256, oversample=2)
+w_neg = w_neg.propagate_image(pixelscale=5e-6, npix=200, oversample=2)
 
 pupil_pos = lentil.Pupil(amplitude=amp, pixelscale=1/240, focal_length=10)
 pupil_pos.phase = 6e-6 * focus
 w_pos = lentil.Wavefront(650e-9)
 w_pos *= pupil_pos
-w_pos = w_pos.propagate_image(pixelscale=5e-6, npix=256, oversample=2)
-
-plt.subplot(121)
-plt.imshow(w_neg.intensity, origin='lower')
-plt.title('Negative focus')
-plt.xticks(np.linspace(0, 512, 5), labels=np.linspace(-1, 1, 5))
-plt.yticks(np.linspace(0, 512, 5), labels=np.linspace(-1, 1, 5))
-
-plt.subplot(122)
-plt.imshow(w_pos.intensity, origin='lower')
-plt.title('Positive focus')
-plt.xticks(np.linspace(0, 512, 5), labels=np.linspace(-1, 1, 5))
-plt.yticks(np.linspace(0, 512, 5), labels=np.linspace(-1, 1, 5))
+w_pos = w_pos.propagate_image(pixelscale=5e-6, npix=200, oversample=2)
+
+fig, axs = plt.subplots(1, 2)
+
+ax1 = axs[0]
+ax1.imshow(w_pos.intensity, origin='lower')
+ax1.set_title('Image plane (+focus)')
+ax1.set_xticks(np.linspace(0, 400, 5), labels=np.linspace(-1, 1, 5))
+ax1.set_yticks(np.linspace(0, 400, 5), labels=np.linspace(-1, 1, 5))
+ax1.set_xlabel('[mm]')
+
+ax2 = axs[1]
+ax2.imshow(w_neg.intensity, origin='lower')
+ax2.set_title('Image plane (-focus)')
+ax2.set_xticks(np.linspace(0, 400, 5), labels=np.linspace(-1, 1, 5))
+ax2.set_yticks(np.linspace(0, 400, 5), labels=np.linspace(-1, 1, 5))
+ax2.set_xlabel('[mm]')
 
 plt.tight_layout()
diff --git a/docs/_img/python/npix_prop.py b/docs/_img/python/npix_prop.py
@@ -14,7 +14,7 @@
 
 w2 = lentil.Wavefront(wavelength=500e-9)
 w2 *= pupil
-w2 = w2.propagate_image(pixelscale=5e-6, npix=128, npix_prop=48, oversample=5)
+w2 = w2.propagate_image(pixelscale=5e-6, npix=128, npix_prop=40, oversample=5)
 
 plt.subplot(1, 2, 1)
 plt.imshow(w1.intensity, origin='lower')

diff --git a/docs/_img/python/tilt_images.py b/docs/_img/python/tilt_images.py
@@ -12,36 +12,39 @@
 py = lentil.Pupil(focal_length=10, pixelscale=1 / 240, amplitude=amp, phase=y_tilt)
 wy = lentil.Wavefront(650e-9)
 wy *= py
-wy = wy.propagate_image(pixelscale=5e-6, npix=256, oversample=5)
+wy = wy.propagate_image(pixelscale=5e-6, npix=200, oversample=5)
 
 px = lentil.Pupil(focal_length=10, pixelscale=1 / 240, amplitude=amp, phase=x_tilt)
 wx = lentil.Wavefront(650e-9)
 wx *= px
-wx = wx.propagate_image(pixelscale=5e-6, npix=256, oversample=5)
+wx = wx.propagate_image(pixelscale=5e-6, npix=200, oversample=5)
 
 plt.subplot(2, 2, 1)
 plt.imshow(x_tilt, origin='lower')
-plt.title('Pupil plane [$+R_x$]')
-plt.xticks(np.linspace(0, 256, 5), labels=np.linspace(-1, 1, 5))
-plt.yticks(np.linspace(0, 256, 5), labels=np.linspace(-1, 1, 5))
-# plt.grid()
+plt.title('Pupil plane ($+R_x$)')
+plt.xticks(np.linspace(0, 256, 5), labels=np.linspace(-0.5, 0.5, 5))
+plt.yticks(np.linspace(0, 256, 5), labels=np.linspace(-0.5, 0.5, 5))
+plt.xlabel('[m]')
 
 plt.subplot(2, 2, 2)
 plt.imshow(y_tilt, origin='lower')
-plt.title('Pupil plane [$+R_y$]')
-plt.xticks(np.linspace(0, 256, 5), labels=np.linspace(-1, 1, 5))
-plt.yticks(np.linspace(0, 256, 5), labels=np.linspace(-1, 1, 5))
-# plt.grid()
+plt.title('Pupil plane ($+R_y$)')
+plt.xticks(np.linspace(0, 256, 5), labels=np.linspace(-0.5, 0.5, 5))
+plt.yticks(np.linspace(0, 256, 5), labels=np.linspace(-0.5, 0.5, 5))
+plt.xlabel('[m]')
 
 plt.subplot(2, 2, 3)
 plt.imshow(wx.intensity ** 0.2, origin='lower')
-plt.title('Image plane [$+R_x$]')
-plt.xticks(np.linspace(0, 256 * 5, 5), labels=np.linspace(-1, 1, 5))
-plt.yticks(np.linspace(0, 256 * 5, 5), labels=np.linspace(-1, 1, 5))
+plt.title('Image plane ($+R_x$)')
+plt.xticks(np.linspace(0, 200 * 5, 5), labels=np.linspace(-1, 1, 5))
+plt.yticks(np.linspace(0, 200 * 5, 5), labels=np.linspace(-1, 1, 5))
+plt.xlabel('[mm]')
+
 plt.subplot(2, 2, 4)
 plt.imshow(wy.intensity ** 0.2, origin='lower')
-plt.title('Image plane [$+R_y$]')
-plt.xticks(np.linspace(0, 256 * 5, 5), labels=np.linspace(-1, 1, 5))
-plt.yticks(np.linspace(0, 256 * 5, 5), labels=np.linspace(-1, 1, 5))
+plt.title('Image plane ($+R_y$)')
+plt.xticks(np.linspace(0, 200 * 5, 5), labels=np.linspace(-1, 1, 5))
+plt.yticks(np.linspace(0, 200 * 5, 5), labels=np.linspace(-1, 1, 5))
+plt.xlabel('[mm]')
 
 plt.tight_layout()
diff --git a/docs/_img/tikz/coordinate_system_2d.tex b/docs/_img/tikz/coordinate_system_2d.tex
@@ -0,0 +1,19 @@
+\documentclass{standalone}
+\usepackage{tikz}
+\usepackage{textcomp}
+
+\begin{document}
+
+\begin{tikzpicture}
+
+\draw [thick, fill=gray, fill opacity=0.1] (0,0) -- (3,0) -- (3,3) -- (0,3) -- cycle;
+\draw[-latex] (-0.25,1.5) -- (3.5,1.5);
+\node [right] at (3.5, 1.5) {$+x$};
+\draw[-latex] (1.5,-0.25) -- (1.5,3.5);
+\node [above] at (1.5, 3.5) {$+y$};
+\draw[fill=black] (1.5,1.5) circle [radius=0.03];
+\draw (1.5,1.5) circle [radius=0.1];
+\node [above right] at (1.5, 1.5) {$+z$};
+
+\end{tikzpicture}
+\end{document}
diff --git a/docs/_img/tikz/coordinate_system.tex → docs/_img/tikz/coordinate_system_3d.tex b/docs/_img/tikz/coordinate_system.tex → docs/_img/tikz/coordinate_system_3d.tex
diff --git a/docs/_img/tikz/focus_direction.tex b/docs/_img/tikz/focus_direction.tex
@@ -33,7 +33,7 @@
     \draw [densely dotted] (0.5,-1.74) -- (5,0);
 
     \draw [latex-] (0.5,-1.8) -- (1,-2.5);
-    \node [below] at (1,-2.5) {$+\mbox{OPD}$};
+    \node [below] at (1,-2.5) {$-\mbox{Focus}$};
 
     \draw [latex-] (5,-0.1) -- (5,-0.8);
     \node [below] at (5,-0.8) {$-\Delta z$};
@@ -48,7 +48,7 @@
     \draw [dashed] (-0.5,-1.74) -- (7,0);
 
     \draw [latex-] (-0.5,-1.8) -- (-1,-2.5);
-    \node [below] at (-1,-2.5) {$-\mbox{OPD}$};
+    \node [below] at (-1,-2.5) {$+\mbox{Focus}$};
 
     \draw [latex-] (7,-0.1) -- (7,-0.8);
     \node [below] at (7,-0.8) {$+\Delta z$};

diff --git a/docs/_img/tikz/propagate_tilt_angle.tex b/docs/_img/tikz/propagate_tilt_angle.tex
@@ -28,7 +28,7 @@
     \draw[color=gray] (0,2,0) -- (-1.4,1.4,\zimg);
 
     \draw[thick, shade, shading=axis, left color=viridisblue, right color=viridisyellow, middle color=viridisgreen,
-    shading angle=30, opacity=0.75] (0,0) circle [radius=2];
+    shading angle=210, opacity=0.75] (0,0) circle [radius=2];
     \draw[color=darkgray] (-2,0,0) -- (2,0,0);
     \draw[color=darkgray] (0,-2,0) -- (0,2,0);
 
@@ -45,7 +45,7 @@
 
     \draw[latex-] (-1.2,1.75,\zimg) -- (-1.4,1.9,9);
     \node [align=center, right] at (-1.4,1.9,9) {Image plane chip};
-    \node [align=center, right] at (-1.4,1.5,9) {\texttt{npix\_chip x npix\_chip}};
+    \node [align=center, right] at (-1.4,1.5,9) {\texttt{npix\_prop x npix\_prop}};
 
 
     \draw[dashed] (-1,-1,\zimg) -- (1,-1,\zimg) -- (1,1,\zimg) -- (-1,1,\zimg) -- cycle;

diff --git a/docs/_img/tikz/propagate_tilt_angle_steps.tex b/docs/_img/tikz/propagate_tilt_angle_steps.tex
@@ -42,7 +42,7 @@
     \draw[color=gray] (0,-0.4,0\zimg) -- (0,0.4,\zimg);
 
     \node [align=center] at (0,-1,\zimg) {Image plane chip};
-    \node [align=center] at (0,-1.4,\zimg) {\texttt{npix\_chip x npix\_chip}};
+    \node [align=center] at (0,-1.4,\zimg) {\texttt{npix\_prop x npix\_prop}};
 
 
     % psf location

diff --git a/docs/_img/tikz/propagate_tilt_phase.tex b/docs/_img/tikz/propagate_tilt_phase.tex
@@ -28,7 +28,7 @@
     \draw[color=gray] (0,2,0) -- (-0.5,0.5,\zimg);
 
     \draw[thick, shade, shading=axis, left color=viridisblue, right color=viridisyellow, middle color=viridisgreen,
-    shading angle=30, opacity=0.75] (0,0) circle [radius=2];
+    shading angle=210, opacity=0.75] (0,0) circle [radius=2];
     \draw[color=darkgray] (-2,0,0) -- (2,0,0);
     \draw[color=darkgray] (0,-2,0) -- (0,2,0);
 

diff --git a/docs/_img/tikz/propagate_tilt_phase_wrap.tex b/docs/_img/tikz/propagate_tilt_phase_wrap.tex
@@ -28,7 +28,7 @@
     \draw[color=gray] (0,2,0) -- (-1,0.5,\zimg);
 
     \draw[thick, shade, shading=axis, left color=viridisblue, right color=viridisyellow, middle color=viridisgreen,
-    shading angle=30, opacity=0.75] (0,0) circle [radius=2];
+    shading angle=210, opacity=0.75] (0,0) circle [radius=2];
     \draw[color=darkgray] (-2,0,0) -- (2,0,0);
     \draw[color=darkgray] (0,-2,0) -- (0,2,0);
 

diff --git a/docs/_static/css/lentil.css b/docs/_static/css/lentil.css
@@ -43,6 +43,10 @@ img {
     margin-bottom: 1.125rem;
 }
 
+img.logo {
+    margin-bottom: 0;
+}
+
 :target:before{
     content:"";
     display:block;

diff --git a/docs/_static/img/coordinate_system_2d.png b/docs/_static/img/coordinate_system_2d.png
diff --git a/docs/_static/img/coordinate_system.png → docs/_static/img/coordinate_system_3d.png b/docs/_static/img/coordinate_system.png → docs/_static/img/coordinate_system_3d.png
diff --git a/docs/_static/img/focus_direction.png b/docs/_static/img/focus_direction.png
diff --git a/docs/_static/img/propagate_tilt_angle.png b/docs/_static/img/propagate_tilt_angle.png
diff --git a/docs/_static/img/propagate_tilt_angle_steps.png b/docs/_static/img/propagate_tilt_angle_steps.png
diff --git a/docs/_static/img/propagate_tilt_phase.png b/docs/_static/img/propagate_tilt_phase.png
diff --git a/docs/_static/img/propagate_tilt_phase_wrap.png b/docs/_static/img/propagate_tilt_phase_wrap.png
diff --git a/docs/reference.rst b/docs/reference.rst
@@ -7,7 +7,7 @@ API reference
 *************
 
 This page gives an overview of all public functions, modules, and objects included
-in Lentil. All classes and functions exposed in the ``lentil.*`` namespace are public.
+in Lentil. All classes and functions exposed in the ``lentil`` namespace are public.
 
 Some subpackages are public including ``lentil.radiometry`` and
 ``lentil.detector``.

diff --git a/docs/user_guide/coordinates.rst b/docs/user_guide/coordinates.rst
@@ -8,26 +8,25 @@ Coordinate system
 .. |Image| replace:: :class:`~lentil.Image`
 
 Lentil adopts the widely used convention of aligning the z-axis along the direction
-of light propagation through an optical system. By the right hand rule, it follows that
-the remaining axes are oriented as shown in the figure below:
+of light propagation through an optical system. For a right-handed coordinate system,
+it follows that the remaining axes are oriented as shown in the figure below:
 
-
-.. image:: /_static/img/coordinate_system.png
+.. image:: /_static/img/coordinate_system_3d.png
     :width: 500px
     :align: center
 
 When viewing a plane in 2D, the z-axis comes out of the screen with the
 positive x-axis pointing to the right and the positive y-axis pointing up.
 
-Lentil also adopts the right hand rule convention for rotations about the coordinate
-system defined above:
+.. image:: /_static/img/coordinate_system_2d.png
+    :width: 225px
+    :align: center
 
-* Rotations in +x rotate the yz plane counter-clockwise about the x-axis
-* Rotations in +y rotate the xz plane counter-clockwise about the y-axis
-* Rotations in +z rotate the xy plane counter-clockwise about the z-axis
+Additional details on the sign conventions for representing wavefront error and
+of the complex exponential in the Fourier kernel are provided below:
 
-.. plot:: _img/python/tilt_images.py
-    :scale: 50
+* :ref:`user_guide.wavefront_error.sign`
+* :ref:`user_guide.diffraction.sign`
 
 .. note::
 

diff --git a/docs/user_guide/diffraction.rst b/docs/user_guide/diffraction.rst
@@ -270,49 +270,65 @@ The chirp Z-transform provides additional efficiency when transforming large arr
 Lentil selects the most appropriate DFT method automatically based on the plane size and
 sampling requirements.
 
-.. _user_guide.diffraction.sampling:
+.. _user_guide.diffraction.sign:
 
-Sampling considerations
-=======================
+Sign of the DFT complex exponential
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Lentil adopts the convention that phasors rotate in the counter-clockwise
+direction, meaning their time dependence has the form :math:`\exp(-i\omega t)`.
+While this is an arbitrary choice, it matches the choice made in most classic
+optics texts. The implications of this choice are as follows:
 
-.. plot:: _img/python/dft_discrete_Q_sweep.py
-    :scale: 50
+* Forward propagations use :func:`lentil.fourier.dft2`, `Numpy's fft2 <https://numpy.org/doc/stable/reference/routines.fft.html#implementation-details>`_,
+  or `FFTW's FFTW_FORWARD <http://fftw.org/fftw3_doc/The-1d-Discrete-Fourier-Transform-_0028DFT_0029.html>`_
+* Backward propagations use :func:`lentil.fourier.idft2`, `Numpy's ifft2 <https://numpy.org/doc/stable/reference/routines.fft.html#implementation-details>`_,
+  or `FFTW's FFTW_BACKWARD <http://fftw.org/fftw3_doc/The-1d-Discrete-Fourier-Transform-_0028DFT_0029.html>`_
+* A converging spherical wave is represented by the expression
+  :math:`\exp\left[-i\frac{k}{2z} (x^2 + y^2)\right]`
+* A diverging spherical wave is represented by the expression
+  :math:`\exp\left[i\frac{k}{2z} (x^2 + y^2)\right]`
 
-.. plot:: _img/python/dft_q_sweep.py
-    :scale: 50
 
+.. .. _user_guide.diffraction.sampling:
 
-.. image:: /_static/img/propagate_fourier_period.png
-    :width: 550px
-    :align: center
+.. Sampling considerations
+.. =======================
 
-.. _user_guide.diffraction.tilt:
+.. .. plot:: _img/python/dft_discrete_Q_sweep.py
+..     :scale: 50
 
-Working with large tilts
-========================
-.. image:: /_static/img/propagate_tilt_phase.png
-    :width: 450px
-    :align: center
+.. .. plot:: _img/python/dft_q_sweep.py
+..     :scale: 50
 
 
-.. image:: /_static/img/propagate_tilt_phase_wrap.png
-    :width: 650px
-    :align: center
+.. .. image:: /_static/img/propagate_fourier_period.png
+..     :width: 550px
+..     :align: center
 
+.. .. _user_guide.diffraction.tilt:
 
-.. image:: /_static/img/propagate_tilt_angle.png
-    :width: 600px
-    :align: center
+.. Working with large tilts
+.. ========================
+.. .. image:: /_static/img/propagate_tilt_phase.png
+..     :width: 450px
+..     :align: center
 
+.. .. image:: /_static/img/propagate_tilt_phase_wrap.png
+..     :width: 650px
+..     :align: center
 
-.. image:: /_static/img/propagate_tilt_angle_steps.png
-    :width: 600px
-    :align: center
+.. .. image:: /_static/img/propagate_tilt_angle.png
+..     :width: 600px
+..     :align: center
+
+.. .. image:: /_static/img/propagate_tilt_angle_steps.png
+..     :width: 600px
+..     :align: center
 
-.. _user_guide.diffraction.segmented:
+.. .. _user_guide.diffraction.segmented:
 
-Differences for segmented apertures
-===================================
+.. Differences for segmented apertures
+.. ===================================
 
 
 

diff --git a/docs/user_guide/optical_systems.rst b/docs/user_guide/optical_systems.rst
@@ -56,7 +56,7 @@ the wavefront's complex data array:
 
 .. math::
 
-    \mathbf{W_1} = \mathbf{A} \exp(\frac{-2\pi j}{\lambda} \mathbf{\theta}) \circ \mathbf{W_0}
+    \mathbf{W_1} = \mathbf{A} \exp\left(\frac{2\pi j}{\lambda} \mathbf{\theta}\right) \circ \mathbf{W_0}
 
 The plane's :func:`~lentil.Plane.multiply` method also accepts an ``inplace`` argument
 that governs whether the multiplication operation is performed on the wavefront in-place
@@ -112,7 +112,7 @@ with a segmented aperture, as depicted below:
 .. plot:: _img/python/segmask.py
     :scale: 50
 
-This modification is not necessary to achieve physically correct propagations, but can
+This modification is not necessary to achieve accurate propagations, but can
 greatly improve performance. For additional details, see
 :ref:`user_guide.diffraction.segmented`.