feat: add autograd clip notebook example

[groberts-flex]

This example notebook demonstrates autograd through clipped geometries to make a light extraction structure! It uses clip to model a fabrication process and take gradients through it directly.

---

Note

Low Risk
Documentation-only addition (example notebook and images); no library or production code paths change.

Overview
Adds Autograd32ClipOperationLightExtractor.ipynb, a new inverse-design example that walks through remote adjoint optimization when the etched surface is built from boolean ClipOperation geometries (two hexagonal hole lattices combined, default intersection, clipped to a finite pixel).

The notebook optimizes pitches, radii, and relative rotation for upward flux via autograd.value_and_grad and Tidy3D’s Adam helper, then extends the story with a fabrication cleanup step on sub-threshold features and top LEE comparisons (initial vs optimized, raw vs processed, vs a flat reference), including polarization and dipole-position averaging via web.Batch. Supporting assets are referenced under ./img/ (thumbnail and lithography-process schematic), and notebook metadata points at Autograd32ClipOperationLightExtractor.qmd for Quarto publishing.

^{Reviewed by Cursor Bugbot for commit 0c8c769. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Spell Check Report

Autograd32ClipOperationLightExtractor.ipynb:

Cell 1, Line 3: 'micro-LED'
  > This notebook demonstrates how to use `tidy3d` autograd support with boolean `ClipOperation` geometries. We will optimize a finite GaN micro-LED light extractor whose top surface is etched by the intersection of two slightly different hexagonal hole lattices. The design parameters control the two lattice pitches, hole radii, and relative rotation. The relative lateral shift is fixed to zero to preserve the symmetry of the extractor.
Cell 1, Line 5: 'high-angle', 'moire-style'
  > Compared to a strictly periodic texture, this moire-style construction introduces a slowly varying superstructure and a broader set of spatial frequencies across the finite LED pixel. That extra geometric diversity can help scatter guided and high-angle emission into upward radiation, while the pattern is still described by only a few differentiable parameters and physically motivated boolean operations.
Cell 1, Line 9: 'dipole-position', 'fabrication-processed', 'flat-interface'
  > After optimization, we prototype a simple fabrication cleanup step that removes or closes features below a selected process threshold. We then compute normalized top light extraction efficiency (top LEE) using flux monitors: the upward extracted power is divided by the power emitted through a small flux box around the dipole. We compare the raw and fabrication-processed initial and optimized designs against a flat-interface reference, and then check polarization averaging and dipole-position averaging at twice the optimization mesh resolution.
Cell 1, Line 13: 'non-adjoint', 'position-average'
  > > Note: Running the complete notebook launches remote Tidy3D jobs. The optimization loop launches two simulations per iteration through the adjoint workflow, while the LEE and position-average sections launch additional non-adjoint simulations.
Cell 5, Line 1: 'non-adjoint'
  > The helper below lets us set separate mesh densities for optimization and final evaluation. The final non-adjoint LEE evaluations use twice the optimization mesh resolution.
Cell 10, Line 2: 'array-like'
  > """Map normalized design variables to physical geometry parameters.
Cell 10, Line 38: 'array-like'
  > """Convert physical starting parameters into normalized optimizer variables.
Cell 10, Line 67: 'array-like'
  > """Project optimizer variables back into the valid normalized box.
Cell 10, Line 83: 'Comma-separated', 'array-like'
  > """Format normalized variables as readable physical parameter values.
Cell 11, Line 5: 'two-lattice', 'xor'
  > The `operation` variable is set to `"intersection"` for this notebook. Changing it to `"xor"` switches the two-lattice combination to a symmetric difference pattern.
Cell 11, Line 7: 'double-exposure'
  > One physical way to think about the intersection pattern is a double-exposure lithography process. A first exposure writes one hexagonal mask, a second slightly rotated exposure writes another, and only the regions that receive enough combined dose open the resist for etching. The resulting top etch is represented directly in Tidy3D by intersecting the two hole lattices with a `ClipOperation`.
Cell 13, Line 72: 'xor'
  > """Combine two hole lattices with a boolean `ClipOperation`.
Cell 13, Line 88: 'xor'
  > if operation == "xor":
Cell 13, Line 94: 'Air-hole', 'air-etch', 'array-like'
  > """Create the full patterned air-etch geometry from design variables.
Cell 13, Line 159: 'Air-hole', 'air-etch'
  > """Wrap an air-etch geometry as a Tidy3D structure inside GaN.
Cell 13, Line 180: 'GaN-to-air', 'Unpatterned'
  > """Create the flat GaN-to-air reference structure.
Cell 14, Line 3: 'source-power'
  > The optimization simulation uses a `FieldMonitor` above the device, which is compatible with adjoint differentiation. The LEE analysis simulations use flux monitors: a top monitor and a small closed flux box around the dipole for source-power normalization.
Cell 15, Line 2: 'point-dipole'
  > """Create the point-dipole source used for optimization and analysis.
Cell 15, Line 61: 'flux-box'
  > """Create the small flux box used to estimate emitted dipole power.
Cell 16, Line 10: 'array-like', 'fabrication-processed', 'micro-LED'
  > """Build a patterned micro-LED simulation.
Cell 16, Line 62: 'array-like'
  > """Build the differentiable simulation used inside the adjoint objective.
Cell 16, Line 100: 'array-like', 'non-adjoint', 'source-normalization'
  > """Build a non-adjoint simulation for normalized top LEE evaluation.
Cell 16, Line 143: 'GaN-to-air', 'flat-interface', 'unpatterned'
  > """Build the unpatterned flat-interface reference simulation.
Cell 21, Line 3: 'frequency-averaged'
  > Our figure of merit is the frequency-averaged upward flux through the top `FieldMonitor`. The objective returns a scalar so `autograd.value_and_grad` can differentiate it with respect to the five design parameters.
Cell 22, Line 2: 'Frequency-averaged', 'array-like'
  > """Evaluate the scalar adjoint objective for a candidate design.
Cell 30, Line 3: 'minimum-feature'
  > The raw adjoint result may contain tiny etched islands, thin bridges, or narrow unetched gaps. Those features can be numerically meaningful in the boolean geometry, but they may not survive a real lithography and etch process. Here we prototype a simple cleanup for both the initial and optimized designs: convert each `ClipOperation` slice to Shapely polygons, apply a minimum-feature rule, then convert the cleaned polygons back into `PolySlab` geometry for final evaluation.
Cell 30, Line 5: 'larger-scale', 'postprocessed'
  > This cleanup is not a differentiable operation as written, so we do not include it directly in the optimization. It is meant to model what may happen in practice when applying this fabrication technique. By evaluating both raw and postprocessed designs, we check that the optimized result does not depend on tiny features produced by the raw boolean geometry, and instead reflects the larger-scale pattern found by the optimizer.
Cell 31, Line 28: 'display-oriented', 'top-view'
  > """Extract the 2D etch cross section from a Tidy3D geometry.
Cell 31, Line 57: 'equivalent-diameter'
  > """Remove disconnected etched components below an equivalent-diameter threshold.
Cell 31, Line 81: 'Fabrication-processed'
  > """Apply a simple fabrication cleanup to a 2D etch pattern.
Cell 31, Line 121: 'LinearRing'
  > """Convert a Shapely linear ring to Tidy3D polygon vertices.
Cell 31, Line 176: 'Fabrication-processed', 'air-etch', 'top-view'
  > """Convert processed Shapely etch regions back to Tidy3D geometry.
Cell 32, Line 32: 'array-like'
  > """Plot raw, processed, and changed etch regions for one design.
Cell 34, Line 5: 'fabrication-processed', 'finite-pixel', 'flat-interface'
  > We use only top LEE for the comparisons below. All final LEE simulations use `analysis_grid_spec`, which is set to twice the mesh resolution used during optimization. When `use_cleaned_design_for_analysis` is `True`, fabrication-processed versions of both the initial and optimized designs are included as additional comparisons. This avoids mixing the finite-pixel sidewall flux with the flat-interface reference, where lateral flux does not represent useful extraction from a finite LED sidewall.
Cell 35, Line 2: 'Frequency-resolved'
  > """Compute top light extraction efficiency from analysis simulation data.
Cell 35, Line 21: 'frequency-resolved'
  > """Package one LEE result into a row for a pandas dataframe.
Cell 36, Line 3: 'GaN-to-air'
  > We first evaluate the center dipole for `Ex` and `Ey` polarizations for the raw and processed initial and optimized designs, plus a flat GaN-to-air reference.
Cell 39, Line 41: 'polarization-resolved'
  > ax.set_title("polarization-resolved center dipole extraction")
Cell 46, Line 22: 'position-dependent'
  > ax[1].set_title("position-dependent top extraction")
Cell 47, Line 3: 'micro-LED', 'top-flux'
  > This example used `ClipOperation` geometry to build a compact micro-LED surface texture from two intersecting hexagonal hole lattices. The design parameters flowed through the boolean geometry, the Tidy3D remote adjoint solve, and the scalar top-flux objective into a Tidy3D Adam optimization loop.
Cell 47, Line 5: 'fabrication-processed', 'flat-interface', 'non-adjoint', 'small-feature'
  > The final analysis used independent flux monitors to normalize the upward extracted power by the emitted dipole power. It compared the raw and fabrication-processed initial and optimized designs against a flat-interface reference using top LEE, then averaged over in-plane dipole polarizations and lateral source positions. The final non-adjoint evaluations were run at twice the mesh resolution used during optimization after small-feature cleanup was applied.

---

Checked 1 notebook(s). Found spelling errors in 1 file(s).
Generated by GitHub Action run: https://github.com/flexcompute/tidy3d-notebooks/actions/runs/28265075083

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 0c8c769. Configure here.}

[cursor]

Dipole grid spans two wavelengths

Low Severity

The dipole position grid is described as spanning one wavelength laterally, but build_lateral_source_positions uses offset=center_wavelength, placing samples at ±λ and giving a 2λ extent in x and y. Position-averaged top LEE therefore samples a wider active region than the text claims.

 

^{Reviewed by Cursor Bugbot for commit 0c8c769. Configure here.}

[marcorudolphflex]

Cool work, great feature!
All in all, I would just make it much shorter (mostly by cleaning code and docs).

Also some formalities:

• point this branch to pre/v2.12
• ensure that the metadata are complete (feature image, title, description, keyowrds)
• fix ruff linting
• ensure dictionary is complete (see spell checks)
• ensure entry in docs/features/autograd.rst

Regarding the notebook itself:

• avoid autograd32 naming of tasks to be robust against future migrations and not confuse non-repo users
• would remove the output cell containing WARNING: Using canonical configuration directory
• The notebook's first sentence comes with "autograd support with boolean ClipOperation geometries". I am not sure if any reader understand the term ClipOperation here? Maybe better explain that more understandable?
• not sure if this is that important to mention in the setup? "The optimizer is Tidy3D's built-in Adam helper from tidy3d.plugins.autograd." - I think this is later repeated anyways
• consider some explanatory comments or named subsections in the cell which defines constants (starting with air_index = 1.0)
• consider removal or shortage of some docstrings. For example, I wouldn't have more than 1 line docstring for format_params or project_params
• is there a reason for a separate cell containing operation = "intersection"?
• The notebook could be more compact. Do we need an own function for build_interface_reference_structure, build_static_gan_structures, build_lateral_source_positions or build_traced_etch_structure, they are called once in the entire notebook
• "Adam minimizes by default, so we pass the negative gradient to maximize the upward extracted flux." Note that our Adam has a direction arg which can be set to max here
• let's make use of the adjoint-capable FluxMonitor
• make introductory image bigger
• do we want to print the first value_and_grad = ag.value_and_grad(objective) - or should it be more of a smoke check?
• build_optimization_simulation exposes operation, source_center, source_polarization, and grid_spec, but the optimization path always uses the same values. We could just simplify to params. Also check other arguments which are either constants or use defaults which are never excited like monitors=None in build_simulation
• top_spectrum is never used? calculate_top_lee may be expanded inside summarize_lee_result
• not sure if this is confusing for users: "No Flexcredit cost for the whole batch as all simulations were restored from local cache." Could someone misunderstand this and assume a free simulation?
• "Our figure of merit is the frequency-averaged upward flux" - but monitor_freqs is just a single freq0?
• cleaned_etch_multipolygon and cleaned_etch_geometry are not used?
• I think the md text in "Fabrication Cleanup Prototype" should mention that we went for fabrication_cleanup_mode = "open_close". Also I wonder if we need to show the other variants like open/close or area only when we go for one in the end and do not really evaluate others? Would make things shorter and put more focus on the rest.
• "we sample a small lateral grid spanning one wavelength in the x and y directions", isn't it 2 wavelengths having [-0.5, 0, 0.5] -> total span of 1 um = 2 * 0.5 um?
• can't we just merge the polarization-resolved center dipole extraction and center dipole extraction plot? (cell 25/27). Would make things shorter and less redundant.
• I had some visual analytics course a couple of years ago and they told us to never connect points if there is not really an intuition for an interpolation which is the case for the "position-dependent top extraction" - can't we just make 3x3 bar plots? This would also make the introduction of source position indices less important - We could think about dropping the table.