Update docs and examples (#91)

* Update docs and examples

* Update ruff configuration to ignore E741 and add noqa comments in laguerre_gaussian files

Author: MatthewFilipovich

README.md

@@ -19,12 +19,12 @@ Learn more in our [paper on arXiv](https://arxiv.org/abs/2411.18591).
 
 ## Key Features
 
-- 🌊 **Differentiable Wave Optics** — Model, analyze, and optimize optical systems using Fourier optics.
-- 🔥 **Built on PyTorch** — GPU acceleration, batch processing, and automatic differentiation.
-- 🛠️ **End-to-End Optimization** — Joint optimization of optical hardware and machine learning models.
-- 🔬 **Optical Elements** — Lenses, phase/amplitude modulators, detectors, polarizers, and more.
-- 🖼️ **Spatial Profiles** — Hermite-Gaussian, Laguerre-Gaussian, Zernike modes, gratings, and others.
-- 🔆 **Polarization and Coherence** — Simulate polarized light and fields with arbitrary spatial coherence.
+- 🌊 **Differentiable Wave Optics:** Model, analyze, and optimize optical systems using Fourier optics.
+- 🔥 **Built on PyTorch:** GPU acceleration, batch processing, and automatic differentiation.
+- 🛠️ **End-to-End Optimization:** Joint optimization of optical hardware and machine learning models.
+- 🔬 **Optical Elements:** Lenses, phase/amplitude modulators, detectors, polarizers, and more.
+- 🖼️ **Spatial Profiles:** Hermite-Gaussian, Laguerre-Gaussian, Zernike modes, gratings, and others.
+- 🔆 **Polarization and Coherence:** Simulate polarized light and fields with arbitrary spatial coherence.
 
 
 ## Installation
@@ -41,7 +41,7 @@ Full documentation is available at [torchoptics.readthedocs.io](https://torchopt
 
 ### Wave Propagation
 
-Simulate free-space propagation of an octagonal aperture:
+Simulate free-space propagation of an octagonal aperture ([full example](https://torchoptics.readthedocs.io/en/stable/examples/optical_phenomena/animate_propagation.html)):
 
 ```python
 import torch
@@ -65,8 +65,7 @@ for z in torch.linspace(0, 2, 11):
 
 ### 4f Imaging System
 
-Simulate a 4f system with a high-pass spatial filter:
-
+Simulate a 4f system with a high-pass spatial filter ([full example](https://torchoptics.readthedocs.io/en/stable/examples/optical_systems/4f_system.html)):
 ```python
 import torch
 import torchoptics
@@ -99,7 +98,7 @@ for i in range(5):
 
 ### Inverse Design
 
-Train a diffractive optical system to convert a Gaussian beam into a petal beam:
+Train a diffractive optical system to convert a Gaussian beam into a petal beam ([full example](https://torchoptics.readthedocs.io/en/stable/examples/optimization/training_petal_beam.html)):
 
 ```python
 import torch

docs/source/conf.py

@@ -53,13 +53,12 @@
     "matplotlib_animations": (True, "jshtml"),
     "subsection_order": ExplicitOrder(
         [
-            "../../examples/basics",
-            "../../examples/beam_modes",
+            "../../examples/optical_phenomena",
             "../../examples/optical_systems",
-            "../../examples/advanced",
+            "../../examples/aberrations",
+            "../../examples/coherence_and_polarization",
             "../../examples/optimization",
-            "../../examples/quantum_computing",
-            "../../examples/quantum_states",
+            "../../examples/quantum",
         ]
     ),
 }

docs/source/quickstart/index.rst

@@ -11,9 +11,8 @@ Before starting, make sure TorchOptics is installed (:ref:`installation`).
 Overview
 --------
 
-TorchOptics simulates optical systems using `Fourier optics
-<https://en.wikipedia.org/wiki/Fourier_optics>`_, where light is modeled as complex-valued
-wavefronts sampled on 2D grids. Built on `PyTorch <https://pytorch.org/>`_, every operation is
+TorchOptics simulates optical systems using Fourier optics, where light is modeled as complex-valued
+wavefronts sampled on 2D grids. Built on PyTorch, every operation is
 fully differentiable, enabling gradient-based optimization of optical designs.
 
 The library is built around three core abstractions:
@@ -26,7 +25,7 @@ The library is built around three core abstractions:
 - :class:`~torchoptics.System` — An ordered sequence of elements forming a complete optical setup,
   analogous to :class:`torch.nn.Sequential`.
 
-Two global defaults control the simulation grid:
+Two global defaults set the physical scale of the simulation:
 
 - **Spacing** — Physical distance between adjacent grid points (meters).
 - **Wavelength** — Wavelength of the monochromatic light (meters).
@@ -47,7 +46,7 @@ subsequent fields and elements will inherit:
     from torchoptics.elements import AmplitudeModulator, Lens
     from torchoptics.profiles import checkerboard, circle, gaussian
 
-    torchoptics.set_default_spacing(10e-6)      # 10 µm grid spacing
+    torchoptics.set_default_spacing(10e-6)       # 10 µm grid spacing
     torchoptics.set_default_wavelength(700e-9)   # 700 nm (red light)
 
 
@@ -63,8 +62,8 @@ Let's create a field from a circular aperture:
 .. plot::
     :context: close-figs
 
-    shape = 500  # 500×500 grid
-    field = Field(circle(shape, radius=1e-3))
+    shape = 1000  # 1000×1000 grid (10 mm × 10 mm physical extent)
+    field = Field(circle(shape, radius=2e-3))
     field.visualize(title="Circular Aperture (z = 0)")
 
 Use :meth:`~torchoptics.Field.propagate_to_z` to propagate a field through free space. As light
@@ -74,13 +73,13 @@ travels, it diffracts, producing characteristic patterns at different distances:
     :context: close-figs
 
     # Near-field (Fresnel) diffraction
-    field.propagate_to_z(0.1).visualize(title="z = 0.1 m  (Fresnel region)")
+    field.propagate_to_z(0.5).visualize(title="z = 0.5 m  (Fresnel region)")
 
 .. plot::
     :context: close-figs
 
-    # Far-field (Fraunhofer) diffraction — the Airy pattern
-    field.propagate_to_z(2.0).visualize(title="z = 2.0 m  (Fraunhofer region)")
+    # Far-field (Fraunhofer) diffraction: the Airy pattern
+    field.propagate_to_z(10.0).visualize(title="z = 10.0 m  (Fraunhofer region)")
 
 Close to the aperture (the Fresnel region), diffraction produces fringes near the edges. Far away
 (the Fraunhofer region), the wavefront converges to the `Airy pattern
@@ -101,22 +100,25 @@ a quadratic phase factor with a circular aperture to the incident field:
 
 .. math::
 
-    \mathcal{M}(x, y) = \operatorname{circ}(r) \cdot
+    \mathcal{M}(x, y) = \operatorname{circ}\!\left(\frac{r}{R}\right) \cdot
     \exp\!\left(-i \frac{\pi}{\lambda f}(x^2 + y^2)\right)
 
+where :math:`r = \sqrt{x^2 + y^2}`, :math:`R` is the aperture radius (half the lens's
+physical extent), :math:`\lambda` is the wavelength, and :math:`f` is the focal length.
+
 Calling an element on a field (``lens(field)``) applies this transformation. Let's focus a Gaussian
-beam with a 200 mm lens:
+beam with a 400 mm lens:
 
 .. plot::
     :context: close-figs
 
-    gaussian_beam = Field(gaussian(shape, waist_radius=1.5e-3))
+    gaussian_beam = Field(gaussian(shape, waist_radius=3e-3))
     gaussian_beam.visualize(title="Gaussian Beam (z = 0)")
 
 .. plot::
     :context: close-figs
 
-    f = 200e-3  # Focal length: 200 mm
+    f = 1  # Focal length: 1 m
     lens = Lens(shape, f, z=0)
 
     focused = lens(gaussian_beam).propagate_to_z(f)
@@ -134,21 +136,23 @@ Use :meth:`~torchoptics.System.measure_at_z` to compute the field at any :math:`
 
 As an example, let's build a `4f system
 <https://en.wikipedia.org/wiki/Fourier_optics#4F_Correlator>`_: two lenses separated by
-:math:`2f` with a spatial filter at the Fourier plane. Here we place a high-pass filter that
+:math:`2f` with a spatial filter at the Fourier plane (:math:`z = 2f`). The system relays the
+input image to the output plane (:math:`z = 4f`), while the Fourier plane in between gives direct
+access to the spatial frequency content for filtering. Here we place a high-pass filter that
 blocks low spatial frequencies, extracting edges from a checkerboard:
 
 .. plot::
     :context: close-figs
 
-    input_field = Field(checkerboard(shape, tile_length=200e-6, num_tiles=15))
+    input_field = Field(checkerboard(shape, tile_length=400e-6, num_tiles=15))
     input_field.visualize(title="Input Field", vmax=1)
 
 .. plot::
     :context: close-figs
 
     # High-pass filter at the Fourier plane (z = 2f)
-    f = 100e-3  # Focal length: 100 mm
-    filter_mask = 1 - circle(shape, radius=300e-6)
+    f = 200e-3  # Focal length: 200 mm
+    filter_mask = 1 - circle(shape, radius=500e-6)
     aperture = AmplitudeModulator(filter_mask, z=2 * f)
 
     aperture.visualize(title="High-Pass Filter at Fourier Plane")
@@ -195,9 +199,7 @@ you can optimize optical designs using gradient descent, the same approach used
 networks.
 
 As an example, let's train a diffractive system to reshape a Gaussian beam into an eight-petal
-beam. The system consists of three :class:`~torchoptics.elements.PhaseModulator` layers, each
-initialized with a flat (zero) phase that will be optimized as a learnable
-:class:`~torch.nn.Parameter`:
+beam. First, we define the input and target fields:
 
 .. plot::
     :context: reset
@@ -219,31 +221,41 @@ initialized with a flat (zero) phase that will be optimized as a learnable
     input_field = Field(gaussian(shape, waist_radius=waist_radius), z=0)
     input_field.visualize(title="Input: Gaussian")
 
+The target is a superposition of two Laguerre-Gaussian modes with opposite orbital angular momentum:
+
+.. math::
+
+    \psi_\text{target} = \mathrm{LG}_0^{+4} + \mathrm{LG}_0^{-4}
+
+whose interference produces an eight-petal intensity pattern.
+
 .. plot::
     :context: close-figs
 
-    # Target: eight-petal beam (LG_0^4 + LG_0^{-4} superposition)
+    # Target: eight-petal beam (LG_0^{+4} + LG_0^{-4} superposition)
     target_data = laguerre_gaussian(shape, p=0, l=4, waist_radius=waist_radius) \
                 + laguerre_gaussian(shape, p=0, l=-4, waist_radius=waist_radius)
-    target_field = Field(target_data, z=0.8).normalize()
+    target_field = Field(target_data, z=0.8).normalize()  # normalize to unit power
     target_field.visualize(title="Target: Petal Beam")
 
+The loss is :math:`1 - |\eta|^2`, where :math:`\eta` is the inner product (mode overlap) between the
+output and target fields: equal to 1 when they are identical and 0 when orthogonal.
+
 .. plot::
     :context: close-figs
 
-    # Trainable diffractive system
+    # Trainable diffractive system: three phase planes initialized to zero
     system = System(
         PhaseModulator(Parameter(torch.zeros(shape, shape)), z=0.2),
         PhaseModulator(Parameter(torch.zeros(shape, shape)), z=0.4),
         PhaseModulator(Parameter(torch.zeros(shape, shape)), z=0.6),
     )
 
-    # The loss function maximizes the squared mode overlap |<output|target>|^2
     optimizer = torch.optim.Adam(system.parameters(), lr=0.05)
     for iteration in range(200):
         optimizer.zero_grad()
         output = system.measure_at_z(input_field, z=0.8)
-        loss = 1 - output.inner(target_field).abs().square()
+        loss = 1 - output.inner(target_field).abs().square()  # 1 - |η|²
         loss.backward()
         optimizer.step()
 
@@ -260,13 +272,13 @@ elements, custom loss functions, and joint optimization with neural networks.
 
 .. tip::
 
-    See the :doc:`training examples </examples/training/index>` for complete inverse design
+    See the :doc:`optimization examples </examples/optimization/index>` for complete inverse design
     workflows with loss curves and animations.
 
 
 Next Steps
 -----------
 
-- :doc:`/examples/index` — Diffraction, polarization, spatial coherence, and inverse design examples.
 - :doc:`/user-guide/index` — In-depth guides on fields, elements, and systems.
+- :doc:`/examples/index` — Diffraction, polarization, spatial coherence, and inverse design examples.
 - :doc:`/api-reference/index` — Complete API documentation.

docs/source/user-guide/configuration.rst

@@ -2,9 +2,9 @@ Configuration
 =============
 
 
-TorchOptics uses two global defaults — **spacing** and **wavelength** — that are applied
+TorchOptics uses two global defaults, **spacing** and **wavelength**, that are applied
 whenever a :class:`~torchoptics.Field` or :class:`~torchoptics.elements.Element` is created
-without explicitly specifying them. Set these at the start of every script.
+without explicitly specifying them.
 
 
 Setting Defaults
@@ -14,7 +14,7 @@ Setting Defaults
 
     import torchoptics
 
-    torchoptics.set_default_spacing(10e-6)       # 10 µm grid spacing
+    torchoptics.set_default_spacing(10e-6)        # 10 µm grid spacing
     torchoptics.set_default_wavelength(700e-9)    # 700 nm wavelength
 
 Retrieve the current values with the corresponding getters:
@@ -24,8 +24,9 @@ Retrieve the current values with the corresponding getters:
     torchoptics.get_default_spacing()       # Returns Tensor
     torchoptics.get_default_wavelength()    # Returns Tensor
 
-If you create a field or element without setting defaults first (and without passing ``spacing``
-or ``wavelength`` explicitly), a ``ValueError`` is raised.
+Set defaults at the start of every script, before creating any fields or elements. If you create
+a field or element without setting defaults first (and without passing ``spacing`` or
+``wavelength`` explicitly), a ``ValueError`` is raised.
 
 
 Spacing
@@ -54,9 +55,10 @@ Spacing can be **isotropic** (scalar) or **anisotropic** (2-element tuple):
 Wavelength
 ----------
 
-The wavelength :math:`\lambda` sets the monochromatic operating wavelength used by propagation
-methods, wavelength-dependent elements like :class:`~torchoptics.elements.Lens`, and profile
-functions like :func:`~torchoptics.profiles.gaussian`.
+The wavelength :math:`\lambda` sets the monochromatic operating wavelength for any
+:class:`~torchoptics.Field` created without an explicit ``wavelength`` argument. It is used by
+propagation algorithms, wavelength-dependent elements like :class:`~torchoptics.elements.Lens`,
+and beam profile functions like :func:`~torchoptics.profiles.gaussian`.
 
 
 Per-Object Overrides
@@ -83,6 +85,8 @@ accuracy for phase-sensitive wave optics. Switch to single precision for faster
 
 .. code-block:: python
 
+    import torch
+
     torchoptics.set_default_dtype(torch.float32)
 
 Only ``torch.float32`` and ``torch.float64`` are supported.