Refactor evaluation and optics APIs with enhanced documentation#112
Merged
singer-yang merged 12 commits intodevfrom Mar 4, 2026
Merged
Refactor evaluation and optics APIs with enhanced documentation#112singer-yang merged 12 commits intodevfrom
singer-yang merged 12 commits intodevfrom
Conversation
…pment Enrich all 20 function docstrings in GeoLensEval with physics context, algorithm descriptions, typed args with units/shapes, and cross-references so that AI models can understand and reimplement each evaluation function. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Replace calc_distortion_2D with calc_distortion_radial (derives field angles from self.rfov, consistent with draw_spot_radial pattern) - Remove rfov param from draw_distortion_radial (now self-contained) - Rename distortion_map -> calc_distortion_map, draw_distortion -> draw_distortion_map for naming consistency - Add wavefront_error(), rms_wavefront_error(), draw_wavefront_error() for OPD-based wavefront analysis at the exit pupil - Update callers in geolens.py and test files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
rms_map now accepts an optional `center` arg and returns (rms, centroid). rms_map_rgb calls rms_map three times — green first to obtain the reference centroid, then red and blue with center=green_centroid. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…core Add spot_points() as the single ray-tracing entry point for spot diagrams and RMS maps. Refactor draw_spot_radial, draw_spot_map, and rms_map to use point_source_radial/point_source_grid for physical coordinates, then delegate to spot_points. Add direction parameter (x/y/diagonal) to radial sampling and tuple num_grid support for non-square grids. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Return Ray object from spot_points so callers can use Ray methods directly. Replace the duplicated centroid calculation in rms_map with ray.centroid()[..., :2]. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace sample_parallel and sample_point_source with a single sample_from_fov method that handles both collimated (depth=inf) and diverging (depth=finite) ray bundles. Simplify sample_grid_rays and sample_radial_rays to delegate to the unified API. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Separate the finite-depth (point-source) logic into its own method sample_from_points_by_fov, which converts FOV angles to physical coordinates and delegates to sample_from_points. sample_from_fov now delegates to it for finite depth. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
scale_pupil=1.5 inflated pre-aperture surface clear apertures to ~2x the stop radius because oversampled rays passed front surfaces but were clipped at the aperture. The expand_factor (5-10%) already provides manufacturing margin, making the 1.5x pupil scaling redundant and harmful. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Set `foclen` to `d_sensor` (total track length) in DiffractiveLens initialization and example loaders, ensuring FOV is calculated. - Propagate `foclen` from the underlying lens object in PSFNetLens.
…raint - Rename loss_gap → loss_thickness with TTL (total track length) check - Add ttl_max: 8mm for cellphone, 300mm for camera lenses - Loosen air_max_center from 0.5mm to 1.5mm for cellphone lenses - Increase w_reg from 0.05 to 0.1 for stronger regularization - Fix NaN from invalid ray masking using torch.where (IEEE 754 safety) - Clamp tmax2tmin denominator to prevent Inf from near-zero edge thickness - Remove prune_surf step 4 (edge thickness enforcement) — handled by loss_reg - Unify prune_surf expand_factor to 10% for all lenses Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Rename test_loss_gap_scalar to test_loss_thickness_scalar to match loss_gap → loss_thickness rename - Add GeoLensSeidel and GeoLensSurfOps mixins to API reference and architecture docs - Replace nonexistent prepare_optimization() with get_optimizer() in examples Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request refactors and modernizes the ray sampling and constraint logic in the lens design codebase. The most significant changes are the unification of ray sampling methods under a new, more flexible API (
sample_from_fov), deprecation of older methods, and updates to constraint and loss functions to better reflect physical lens properties. These changes improve code clarity, maintainability, and extendibility.Ray Sampling API Refactor:
sample_from_fovmethod that handles both collimated (infinite-depth) and point-source (finite-depth) ray bundles, replacing the previoussample_parallelandsample_point_sourcemethods and updating all internal calls to use the new API (deeplens/optics/geolens.py). [1] [2] [3] [4] [5] [6] [7] [8]sample_from_points_by_fovfor sampling point-source rays specified by field angles and depth, and extendedsample_radial_raysto support sampling along the x, y, or diagonal directions (deeplens/optics/geolens.py). [1] [2]Constraint and Loss Function Updates:
loss_gapfunction and its references with a newloss_thicknessfunction, which penalizes excessive air gaps, lens thickness, and total track length. Updated related parameter names and documentation (deeplens/optics/geolens_pkg/optim.py). [1] [2] [3] [4] [5]ttl_max) in the optimizer initialization (deeplens/optics/geolens_pkg/optim.py). [1] [2]Diffractive Lens Initialization Consistency:
foclen) is always set based on the sensor distance (d_sensor) and that the field of view is recalculated in diffractive lens examples and initialization (deeplens/optics/diffraclens.py). [1] [2] [3]Minor Fixes and Cleanups:
unwarpto use the correct method namecalc_distortion_map(deeplens/optics/geolens.py).deeplens/optics/geolens.py). [1] [2]These changes collectively modernize the codebase, making it more robust, easier to use, and ready for further extension.