HybridLens API Reference

Note

This API reference is still under development. Some details may contain mistakes or be incomplete.

HybridLens models a hybrid refractive-diffractive optical system that couples a GeoLens with a diffractive optical element (DOE). It uses a differentiable ray–wave pipeline: coherent ray tracing to the DOE plane, DOE phase modulation, and wave propagation to the sensor.

Class Overview

  • Inherits from Lens

  • Internally composes a GeoLens (refractive module) and a DOE (diffractive module)

Main Class

class HybridLens(filename=None, device=None, dtype=torch.float64)

Hybrid refractive–diffractive lens using a differentiable ray–wave model.

Parameters:

  • filename (str or None) – Path to hybrid-lens JSON file. If None, create empty hybrid lens

  • device (str or None) – Computing device ('cuda' or 'cpu'). If None, auto-selects

  • dtype (torch.dtype) – Data type for computations (default: torch.float64)

Note

Sensor size and resolution are read from the lens file (GeoLens section). If not provided, defaults of 8mm x 8mm and 2000x2000 pixels will be used.

Key Attributes:

geolens: GeoLens

Embedded refractive module; handles geometric ray tracing and first-order properties.

doe: diffractive surface (Binary2, Pixel2D, Fresnel, Zernike)

Diffractive optical element mounted after the refractive module.

Initialization & I/O

HybridLens.read_lens_json(filename)

Load a hybrid lens from a JSON file. Internally:

  • Builds the embedded GeoLens from the same JSON

  • Instantiates DOE by param_model (binary2, pixel2d, fresnel, zernike)

  • Appends a placeholder planar surface at the DOE axial position to geolens.surfaces

Parameters:

filename (str) – Path to hybrid JSON file

HybridLens.write_lens_json(lens_path)

Save the hybrid lens to JSON. Writes refractive surfaces (excluding DOE placeholder) and DOE parameters.

Parameters:

lens_path (str) – Output JSON path

HybridLens.double()

Switch internal lens modules to double precision (torch.float64).

Refocusing & Scaling

HybridLens.refocus(foc_dist)

Refocus by updating the embedded GeoLens.refocus(). DOE position stays fixed relative to the refractive module.

Parameters:

foc_dist (float) – Target focus distance in object space (mm)

HybridLens.calc_scale(depth)

Delegate to GeoLens.calc_scale() to compute object-to-image scale for given depth.

Parameters:

depth (float) – Object depth (mm)

Returns:

Scale factor (object height / image height)

Return type:

float

Wavefield & PSF

HybridLens.doe_field(point, wvln=0.589, spp=1000000)

Compute complex wavefront at the DOE plane by coherent ray tracing through the embedded GeoLens.

Parameters:

  • point (list or torch.Tensor) – Point source position [x, y, z] (normalized x,y in [-1, 1], z < 0)

  • wvln (float) – Wavelength in micrometers

  • spp (int) – Rays per point for coherent tracing (should be >= 1e6)

Returns:

(wavefront, psf_center) where wavefront has shape [H, W] and psf_center is [x, y] in normalized sensor coordinates

Return type:

(torch.Tensor, list)

HybridLens.psf(points=[0.0, 0.0, -10000.0], ks=PSF_KS, wvln=DEFAULT_WAVE, spp=SPP_COHERENT)

Monochromatic PSF using ray–wave model:

  1. Coherent ray tracing to DOE plane to get wavefront

  2. Apply DOE phase modulation

  3. Propagate to sensor via Angular Spectrum Method (ASM)

  4. Crop around PSF center and normalize

Parameters:

  • points (list or torch.Tensor) – Point source position [x, y, z] (normalized x,y in [-1, 1], z < 0)

  • ks (int or None) – Output PSF kernel size (pixels). None to return a central crop

  • wvln (float) – Wavelength in micrometers

  • spp (int) – Rays per point for coherent tracing (>= 1e6 recommended)

Returns:

Normalized PSF patch

Return type:

torch.Tensor of shape [ks, ks] (or cropped [h, w] if ks is None)

Visualization

HybridLens.draw_layout(save_name='./DOELens.png', depth=-10000.0, ax=None, fig=None)

Draw the hybrid system layout: refractive ray paths and illustrative wave-propagation arcs from DOE to sensor.

Parameters:

  • save_name (str) – Output figure path

  • depth (float) – Object depth for ray bundles (mm)

  • ax (matplotlib.axes.Axes or None) – Optional matplotlib axis to draw on

  • fig (matplotlib.figure.Figure or None) – Optional matplotlib figure

Returns:

Existing (ax, fig) if provided, otherwise saves to disk

Optimization

HybridLens.get_optimizer(doe_lr=1e-4, lens_lr=[1e-4, 1e-4, 1e-2, 1e-5], lr_decay=0.01)

Construct an Adam optimizer over both refractive parameters (via GeoLens.get_optimizer_params()) and DOE parameters.

Parameters:

  • doe_lr (float) – Learning rate for DOE parameters

  • lens_lr (list) – Learning rates for refractive parameters [d, c, k, a]

  • lr_decay (float) – Decay factor for higher-order aspheric coefficients

Returns:

Configured optimizer

Return type:

torch.optim.Optimizer