Refactor, week of 0414

[singer-yang]

This pull request makes several improvements and cleanups to the optics simulation codebase, particularly in the GeoLens class and related configuration. The main changes include a refactor and enhancement of field-of-view (FoV) calculations, consolidation of ray sampling logic, and improvements to code clarity and maintainability. There are also some import cleanups and documentation improvements.

Field-of-View Calculation and Ray Sampling:

• Refactored the calc_fov method in GeoLens to use forward ray tracing for real FoV calculation, improving robustness for wide-angle lenses and fixing failures in the previous backward-tracing approach. Now, FoV is determined by tracing rays from object space and matching image height to the sensor, with a fallback to effective FoV if tracing fails. [1] [2]
• Unified and simplified the ray sampling API by merging the logic of the removed sample_from_points_by_fov method into sample_from_fov, which now handles both collimated and point-source rays depending on the depth argument. [1] [2] [3]
• Fixed device placement for tensors in several methods (e.g., calc_entrance_pupil, sample_sensor) to ensure compatibility with GPU/CPU execution and prevent device mismatch errors. [1] [2]
• Corrected the calculation of fov_deg in sample_radial_rays to avoid unnecessary conversion and ensure proper units.

Configuration and Documentation:

• Improved and reorganized deeplens/optics/config.py by separating tunable experiment constants from physical/numerical constants, adding extensive comments, and clarifying the purpose of each parameter. No functional changes to values, but greatly improved readability and maintainability.
• Added documentation and logging improvements to deeplens/optics/geolens.py, including tracking of lens design constraints in post_computation. [1] [2] [3] [4] [5] [6]

API and Import Cleanups:

• Updated imports to reflect module reorganization: functions like diff_float and diff_quantize now imported from .ops instead of .utils, and create_lens is imported directly from geolens_pkg. [1] [2] [3]
• Removed unused or redundant arguments and code in curriculum_design (e.g., match_mat parameter and related logic). [1] [2] [3]

These changes collectively improve the accuracy, reliability, and maintainability of the optics simulation codebase.

[Copilot]

Pull request overview

This PR refactors core optics simulation utilities and the GeoLens pipeline, with a focus on more robust field-of-view (FoV) estimation, consolidated ray sampling APIs, and improved device-safe tensor creation. It also reorganizes differentiable ops/imports and updates tests accordingly.

Changes:

• Refactor GeoLens.calc_fov() to a forward-tracing sweep-based FoV estimate with fallback to effective FoV, plus additional constraints initialization in post_computation().
• Consolidate ray sampling by folding point-source-by-FoV sampling into sample_from_fov(), and replace the legacy Ray.obliq with an accumulated bend_penalty.
• Import/organization cleanup: move differentiable ops to deeplens/optics/ops.py, move EDoF helper to deeplens/utils.py, and reduce heavy top-level imports by lazy-importing (skimage/torchvision/tqdm).

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/test_utils.py	Updates imports to reflect ops/util split.
test/test_ray.py	Updates Ray cloning test for bend_penalty attribute.
test/test_geolens_optim.py	Aligns tests with renamed constraints and new loss breakdown.
test/test_basics.py	Removes wave_rgb() tests and keeps constants validation.
deeplens/utils.py	Moves heavy imports to function scope; adds foc_dist_balanced().
deeplens/optics/phase_surface/phase.py	Adds update_r() convenience method for phase surface sizing.
deeplens/optics/ops.py	Narrows module to differentiable tensor ops; removes non-core helpers.
deeplens/optics/light/wave.py	Lazy-imports torchvision/tqdm for IO-heavy methods.
deeplens/optics/light/ray.py	Replaces obliq with bend_penalty and updates cloning/squeeze behavior.
deeplens/optics/lens.py	Lazy-imports torchvision/tqdm in visualization/render loops.
deeplens/optics/imgsim/psf.py	Fixes device placement for new tensors via device=.
deeplens/optics/hybridlens.py	Updates diff_float import to come from ops.
deeplens/optics/geometric_surface/thinlens.py	Ensures f tensor is created on the correct device.
deeplens/optics/geometric_surface/base.py	Adds per-surface bend penalty accumulation in refraction; device-safe tensor creation.
deeplens/optics/geometric_surface/aspheric.py	Improves numerical safety and tensorizes validity checks for compile/tracing.
deeplens/optics/geolens_pkg/vis.py	Improves titles/docs and adjusts default pupil z-reference; adds spot RMS to title.
deeplens/optics/geolens_pkg/psf_compute.py	Updates diff_float import to come from ops.
deeplens/optics/geolens_pkg/optim_ops.py	Refines pruning/shape correction flow and removes numpy dependency in pruning.
deeplens/optics/geolens_pkg/optim_init.py	Fixes device placement when creating d_sensor.
deeplens/optics/geolens_pkg/optim.py	Replaces legacy geometry losses with loss_profile/loss_bound; adds local cosine LR scheduler.
deeplens/optics/geolens_pkg/io.py	Uses WAVE_RGB for Zemax export and removes redundant post_computation() call on JSON read.
deeplens/optics/geolens_pkg/eval.py	Device-safe tensor creation and updated spot computation to pooled polychromatic centroid.
deeplens/optics/geolens_pkg/__init__.py	Exports create_lens from optim_init.
deeplens/optics/geolens.py	Forward-traced FoV calculation; unified sample_from_fov; adds init_constraints() to post_computation().
deeplens/optics/diffractive_surface/diffractive.py	Updates diff_quantize import to come from ops.
deeplens/optics/diffraclens.py	Updates diff_float import to come from ops.
deeplens/optics/config.py	Reorganizes constants into “tunable” vs “physical/numerical” sections with clearer comments.
2_autolens_rms.py	Updates create_lens import path and removes unused curriculum args/logic.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

calc_chief_ray_infinite() converts scalar rfov to a tensor only when rfov > 0. If a caller passes rfov=0.0 (which is a valid/useful case per the docstring), the next line rfov = rfov.to(self.device) will fail because a Python float has no .to(). Handle all scalar rfov values (e.g., int/float, including 0) by converting via torch.as_tensor/torch.tensor before calling .to().

[singer-yang]

@copilot apply changes based on this feedback

[Copilot]

prune_surf() can reference fov_deg before assignment when both self.rfov and self.rfov_eff are None (the previous fallback based on atan(r_sensor/foclen) was removed). This will raise at runtime in the fov_y = ... line. Consider restoring a safe fallback (e.g., compute from r_sensor/foclen) or explicitly raising a clear error if FoV has not been computed yet.

Suggested change

	fov_deg = self.rfov_eff * 180 / torch.pi
	fov_deg = self.rfov_eff * 180 / torch.pi
	elif getattr(self, "r_sensor", None) is not None and getattr(self, "foclen", None) is not None:
	fov_deg = torch.atan(self.r_sensor / self.foclen) * 180 / torch.pi
	else:
	raise ValueError(
	"Cannot prune surfaces because field of view is unavailable: "
	"expected self.rfov or self.rfov_eff to be set, or both "
	"self.r_sensor and self.foclen to be available for fallback computation."
	)