feat: Implement GRIN (Gradient-Index) material and propagation

[zhazhajust]

Summary

This PR implements Gradient-Index (GRIN) material support in Optiland, enabling accurate modeling of optical components with spatially varying refractive indices. Open #337

Key Features

1. GRIN Material Implementation

• New GradientMaterial class in optiland/materials/gradient_material.py
• Supports arbitrary refractive index profiles n(x, y, z)
• Built-in profiles: axial, radial, and gradient distributions
• Extensible API for custom gradient functions

2. GRIN Ray Propagation

• Enhanced GRIN propagation algorithm in optiland/propagation/grin.py
• Numerical ray tracing through gradient-index media using 4th-order Runge-Kutta method
• Bidirectional propagation support (forward and backward)
• Proper handling of reflections at GRIN material boundaries
• Automatic ray tracing step adaptation based on gradient strength

3. Comprehensive Testing

• 269 lines of new tests in tests/propagation/test_grin.py
• Tests for axial, radial, and spherical gradient profiles
• Validation of bidirectional propagation with reflections
• Serialization test coverage

4. Examples and Documentation

• Detailed implementation guide: GRIN_IMPLEMENTATION_SUMMARY.md
• Interactive examples:
  • examples/simple_grin_test.py - Basic GRIN lens behavior
  • examples/grin_reflection_detailed.py - Reflection effects in GRIN media

Changes

• 8 files changed, 1,322 insertions(+), 25 deletions(-)
• Three commits implementing core functionality, testing, and reflection support

Testing

All existing tests pass, plus new comprehensive GRIN material tests covering:

• Axial gradient propagation
• Radial gradient focusing effects
• Spherical gradient profiles
• Bidirectional ray tracing with reflections
• Edge cases and boundary conditions

This implementation enables Optiland to model advanced optical components like GRIN lenses, gradient-index fibers, and other waveguide devices critical in modern optical systems.

[HarrisonKramer]

Hi @zhazhajust,

Thanks for submitting this! It will be a great addition.

I made some minor changes to the functionality, including updating the OPD calculation. I saw you were using an approximation previously.

One thing that is still missing is making it possible to visualize in 2D and 3D. That will involve making updates to track the (x, y, z) position of points as rays propagate through the GRIN media. I am not certain how best to do this, but I would like to have this functionality before we merge the PR. Do you want to take a shot at it? I can also help here.

Lastly, tracing through a GRIN lens will be inherently slower than standard raytracing. However, I wonder if there are any opportunities for optimization here. The raytrace speed is slower than I expected, but perhaps there's no way around this.

Thanks again,
Kramer

[zhazhajust]

Hi @HarrisonKramer,

Sorry for the delayed response — I’ve been tied up with a few other things recently.

Thanks for the improvements you made, especially the fix to the OPD calculation. That definitely addressed a weak spot in my original implementation.

For GRIN ray path visualization, here’s the proposed approach I’m planning to take:

Proposed implementation

• Path recording during GRIN propagation
  Add a record_path option to GRINPropagation that records intermediate (x, y, z) positions at each RK4 integration step.

• Path storage in RealRays
  Extend RealRays with path-related helpers (e.g. start_path_recording, get_path, has_path) to store per-ray trajectory data.

• SurfaceGroup integration
  Add a get_ray_paths() method to aggregate ray path data across surfaces.

• Curved path rendering
  Update the 2D ray visualization in rays.py so rays traversing GRIN media are rendered as continuous curved paths rather than straight segments.

The key idea is that rays propagating through GRIN materials will accumulate position samples during numerical integration, which can then be concatenated across surfaces to visualize the true curved trajectory.

Next steps

• Verify that the 3D visualization pipeline also supports curved ray paths
• Add more comprehensive test coverage
• Treat performance optimizations (e.g. vectorization, adaptive step sizing) as a follow-up once the visualization is in place

Does this direction look reasonable to you? Happy to adjust the approach based on your feedback, or to collaborate on the visualization pieces if that’s helpful.

Thanks again for your input.

[HarrisonKramer]

Hi @zhazhajust,

Thanks for your concrete proposal. I agree with your approach, but I would prefer that the ray path recording is optional for GRIN media (and that it defaults to not recording). In general, users won't need the exact (x, y, z) position of rays as they propagate through the GRIN medium, so it should default to saving ray data only on the surface boundaries, as it does now. The visualization code can then trigger the GRIN ray path recording when it traces rays specifically for visualization in 2D/3D. That might just be a simple Boolean flag (perhaps in GRINPropagation?) that the user can also control. Does that make sense? Do you agree with this proposal?

Thanks,
Kramer