3D air-strip nanocavity

Instructions for Codex and human contributors

Scope and scientific objective

This project builds a 3D free-form nanophotonic cavity inverse-design method with an exact semi-infinite periodic-mirror boundary. The target device has a full air strip for a trapped atom and optical tweezer. Work autonomously within this repository, but treat numerical validation as part of the physics, not as optional post-processing.

Invariants that must never be violated

  • The protected region |x| < air_gap_half_length must have density exactly zero. Check maximum_density_in_air_strip == 0 in every checkpoint.
  • A topology transfer carries geometry only. Never carry Q across a grid, domain, material, mirror, or PML change.
  • The lead boundary must remain the retarded real-axis surface Green function. Do not evaluate the surface decimation directly below the real frequency axis and assume it remains on the outgoing sheet.
  • Keep ordinary-cladding clearance between every possible dielectric voxel and the transverse PML.
  • Preserve complex symmetry (A.T == A numerically). The reciprocal adjoint uses transpose bilinear products, not Hermitian products.
  • Use the exact transpose of every cell-to-edge and topology filter map during backpropagation.
  • Keep curl(grad)=0; do not reintroduce the obsolete grad-div penalty.
  • Maintain x/y/z-reflection-symmetric topology updates until a deliberate symmetry-domain formulation replaces them.
  • Preserve the phase of the mirror period at the defect/lead interface.
  • Do not accept an optimizer step from the differentiable surrogate alone. Rebuild and pass the independent rational/shared-pole validator.

Evidence policy

Use this vocabulary precisely:

  • candidate: a topology with a source-coupled spectral feature;
  • spectrally accepted: holdout, model-order/window, linewidth, and SIMO gates pass on one discretization;
  • PML converged: the same pole identity passes the prescribed transverse absorber perturbations;
  • grid converged: the pole and relevant observables remain stable under controlled resolution/domain refinement;
  • device claim: additionally includes physical materials, mode volume or atom coupling, waveguide beta factor, and fabrication robustness.

Never call Q=921.65 a converged device Q. It is spectrally accepted only on the controlled grid.

Retain failed runs when they expose a distinct failure mechanism. The prior apparent Q=24,867 result is valuable evidence: its topology reached the PML, one reflection mask was asymmetric, and the pole changed catastrophically with absorber parameters.

Required workflow for a topology step

  1. Load a checkpoint and verify the configuration, air-strip mask, and reflection error.
  2. Reacquire the full local cluster after any grid/domain change.
  3. Collect both a wide seven-probe sweep and a dense target-mode sweep.
  4. Run combined_rational_validation.py; stop if accepted is false.
  5. Verify the last full-PML anchor, its exact fingerprint, its evidence age, and the adaptive-policy manifest before using it as prior evidence.
  6. Build a local Loewner gradient while tracking the target upper pole.
  7. Propose one bounded Adam/trust-region update with backtracking.
  8. Independently rebuild the wide/local shared-pole data and combined gate.
  9. Mark the topology spectrally accepted only if mode identity is retained, every spectral gate passes, and Q improves.
  10. Run multipole_pml_convergence.py --validator combined whenever the adaptive cadence or an early trigger requests it; stop if its gate fails.
  11. Call only checkpoints that actually passed that full campaign PML converged. Deferred checkpoints remain spectrally accepted.
  12. Save the full checkpoint, configuration, metrics, PML-policy decision, histories, plots, timing, and peak RSS before another step.

Adaptive transverse-PML cadence

The full seven-case combined PML campaign is mandatory at every grid, domain, material, mirror, PML, or operator change and before a finite campaign ends or a PML-converged milestone is reported. Between those anchors, small bounded topology updates may use the explicit adaptive-pml-v1 policy:

  • begin with every-step validation;
  • after repeated full campaigns pass at margins ten times tighter than the authoritative gate, grow the interval through 1, 2, 3, 5, and at most 8 spectrally accepted steps;
  • force an early full campaign for configuration/topology-shape changes, a one-step pole displacement above 0.15 half-widths, a relative Q change above 5%, or cumulative raw-topology displacement above 0.04 from the last PML anchor; and
  • reset confidence after any full campaign that passes the authoritative gate without meeting the tighter confidence margins.

This is a cadence change, not a weaker PML gate. A scheduled or triggered PML failure remains a scientific stop condition. Never backfill a deferred checkpoint with another topology's PML result, and never describe an unvalidated intermediate checkpoint as PML converged.

Numerical development rules

  • Run python -m unittest discover -v before and after changing physics code.
  • Add a regression test for each new formula or corrected failure mode.
  • Run directional finite differences for new gradients on the smallest useful grid before an expensive sweep.
  • Compare condensed and full-period lead backends on a small grid after any boundary change.
  • Re-run the two-period boundary-translation test after any lead, material-map, PML, or Yee-staggering change.
  • Measure memory with /usr/bin/time -v; estimates are planning aids only.
  • Set BLAS thread variables explicitly. Do not run multiple frequency workers until one process's peak RSS is measured.
  • Prefer restartable, one-step runs and descriptive output directories. Never overwrite the last accepted checkpoint.
  • Treat run_data.npz plus its adjacent config.json as one checkpoint.
  • Inspect metrics.json programmatically rather than inferring acceptance from a plot.

Current next action

The persistent production path is scripts/run_persistent_cooperativity.sh. It expands the accepted defect/lead interface by exactly two mirror periods per side, transfers geometry only, reacquires a fresh 41/449/28-point wide/local/confirmatory cluster, and repeats the combined transverse-PML gate. It may begin topology steps only after those expanded-domain gates pass. The controller then runs without a preset step limit but remains fail-closed at every scientific stop condition.

Architectural boundaries

Keep these roles separate:

  • vector3d_optimizer.py: Maxwell/Yee operator, topology, exact periodic boundary, fixed-frequency LDOS.
  • real-frequency sampling: always uses the retarded surface recursion;
  • differentiable surrogate: local Loewner or implicit real-axis continuation;
  • authoritative validation: held-out, multi-window, multi-probe rational continuation plus independent linewidth/SIMO checks;
  • future physical objectives: atom-position coupling, radiative/intrinsic Q, guided-port beta factor, and fabrication robustness.

AAA support selection and nonlinear shared-pole fitting are not differentiated. Their discontinuities are intentionally kept out of the local gradient.

Before changing the objective

Read DERIVATIONS.md. In particular, distinguish:

  • driven LDOS from a pole objective;
  • a driven-field energy fraction from quasinormal-mode volume;
  • total pole Q from intrinsic/radiative Q and desired waveguide coupling;
  • topology smoothness from fabrication robustness.

Any new objective must state its continuous definition, discrete estimator, gradient, normalization, and independent acceptance test.