# Examples
Each example reproduces a published result: it computes something with photonoxide, prints it
next to the number the paper prints, with the grid and the tolerance, and fails (exit code 1)
when they disagree. CI runs every example.
```sh
cargo run --release --example <name>
```
What each prints is in [`output/`](output), and CI checks that it still prints exactly that.
After changing an example, regenerate its output:
```sh
cargo run --release --quiet --example <name> > examples/output/<name>.txt
```
| Example | What it computes | Checked against | Tolerance |
|---|---|---|---|
| [`silicon_index`](silicon_index.rs) | Silicon's refractive index, 1.3–10 µm | H. H. Li, J. Phys. Chem. Ref. Data 9, 561 (1980), [doi:10.1063/1.555624](https://doi.org/10.1063/1.555624), Table 1 (293 K) | 5e-5 (4 printed decimals) |
| [`silica_index`](silica_index.rs) | Fused silica's refractive index, 0.55–3.2 µm | I. H. Malitson, J. Opt. Soc. Am. 55, 1205 (1965), [doi:10.1364/JOSA.55.001205](https://doi.org/10.1364/JOSA.55.001205), Table I | 1e-6 (6 printed decimals) |
| [`slab_soi`](slab_soi.rs) | TE and TM modes of a 220 nm silicon slab in oxide at 1550 nm, exact | L. Chrostowski, M. Hochberg, *Silicon Photonics Design* (2015), [doi:10.1017/CBO9781316084168](https://doi.org/10.1017/CBO9781316084168), Section 3.2.2 | 5e-4 (3 printed decimals) |
| [`slab_yariv_yeh`](slab_yariv_yeh.rs) | Guided modes of an asymmetric and a symmetric slab, exact | A. Yariv, P. Yeh, *Photonics*, 6th ed., Oxford University Press (2007), Sections 3.1–3.2 (a textbook, no DOI) | 5e-5 (4 printed decimals); mode counts exact |
| [`bend_loss`](bend_loss.rs) | The radiation loss of bent slabs: exact, against Marcuse's formula as the radius grows, and from the full-vector solver with a conformal map and a PML | D. Marcuse, Bell Syst. Tech. J. 50, 2551 (1971), [doi:10.1002/j.1538-7305.1971.tb02620.x](https://doi.org/10.1002/j.1538-7305.1971.tb02620.x), Eqs. 32–33; M. Heiblum, J. H. Harris (1975) | 10 % at 120 µm: the formula is an approximation of order d/R |
| [`effective_index_method`](effective_index_method.rs) | The effective index method on 220 nm strips, 400–600 nm wide, and its error against the full-vector solver in n_eff and n_g | L. Chrostowski, M. Hochberg (2015), Section 3.2.5: 2.489 for 500 nm; G. B. Hocker, W. K. Burns, Appl. Opt. 16, 113 (1977), [doi:10.1364/AO.16.000113](https://doi.org/10.1364/AO.16.000113) | 1e-3: the book's rounded slab index and 10 nm mesh |
| [`group_index`](group_index.rs) | The group index of 220 nm silicon strips, 400–600 nm wide, at 1.55 µm, with the book's dispersive silicon; the TE-like mode tracked over wavelength, on a quarter domain | L. Chrostowski, M. Hochberg, *Silicon Photonics Design* (2015), [doi:10.1017/CBO9781316084168](https://doi.org/10.1017/CBO9781316084168), Fig. 3.22b, read off the plot | 0.02: the plot's reading (±0.005), the book's 20 nm mesh and our corners |
| [`leaky_wire_benchmark`](leaky_wire_benchmark.rs) | The community's leaky SOI wire (500 × 220 nm on 1 µm of oxide on silicon), full-vector with a PML, on graded grids at 5, 2.5 and 1.25 nm, Richardson-extrapolated | P. Bienstman et al., Opt. Quantum Electron. 38, 731 (2006), [doi:10.1007/s11082-006-9025-9](https://doi.org/10.1007/s11082-006-9025-9), Table 6 | 2e-4 in Re (8e-5 found), 2 % in Im (0.25 % found) |
| [`marcatili`](marcatili.rs) | Marcatili's approximation for a rectangular guide (a = 2b, n₁/n₄ = 1.05) against the full-vector solver, his exact and closed-form solutions, from near cutoff to well guided | E. A. J. Marcatili, Bell Syst. Tech. J. 48, 2071 (1969), [doi:10.1002/j.1538-7305.1969.tb01166.x](https://doi.org/10.1002/j.1538-7305.1969.tb01166.x), Fig. 6b and p. 2083 | 5e-4 far from cutoff; his closed form within 5 % ("a few percent") |
| [`multilayer_chilwell`](multilayer_chilwell.rs) | A four-layer planar guide by transfer matrices: its 8 bound modes, the power each puts in every layer, and 5 leaky waves (complex) | J. Chilwell, I. Hodgkinson, J. Opt. Soc. Am. A 1, 742 (1984), [doi:10.1364/JOSAA.1.000742](https://doi.org/10.1364/JOSAA.1.000742), Tables 2–3 | 5e-7 bound, 1.5e-5 leaky (one printed value is a unit off), 0.06 % power |
| [`leaky_waves`](leaky_waves.rs) | The same guide's five TE leaky waves, now from the full-vector solver with a PML absorbing the leakage, 2.5 nm grid | J. Chilwell, I. Hodgkinson (1984), Table 2 | 5e-5 (m = 8, at the cover's cutoff: 2e-4) |
| [`hadley_corners`](hadley_corners.rs) | Four waveguides with dielectric corners (boxes and impinged corners, ε = 2.25 and 8), full-vector with mirror walls, at 8 to 128 cells a side: the standard scheme (about first order at the corners) against Hadley's high-accuracy equations (about second order) | G. R. Hadley, J. Lightwave Technol. 20, 1219 (2002), [doi:10.1109/JLT.2002.800371](https://doi.org/10.1109/JLT.2002.800371), Figs. 4–7 (series expansions, 1e-8) and Figs. 8–11 | at a 7.8 nm grid: 5e-5 for the standard scheme, 1e-6 for Hadley's (2e-7 to 5e-7 found) |
| [`strip_waveguide`](strip_waveguide.rs) | TE-like mode of a 500 × 220 nm silicon strip at 1550 nm, full-vector, at 20, 10 and 5 nm grids | L. Chrostowski, M. Hochberg, *Silicon Photonics Design* (2015), Fig. 3.14 (Lumerical MODE, 20 nm mesh) | 3e-3 at 5 nm: the book's value is good to about 1e-3, and the corners slow convergence here |
| [`circuit_splitter`](circuit_splitter.rs) | A Mach-Zehnder interferometer's arm phase tuned for 30 % in the bar port, by genoxide's L-BFGS-B and Adam on the circuit adjoint's gradient | W. R. Clements et al., Optica 3, 1460 (2016), [doi:10.1364/OPTICA.3.001460](https://doi.org/10.1364/OPTICA.3.001460), Eq. 1 and Fig. 1(c): sin²(θ/2) in the bar port | 1e-6 rad |
| [`circuit_ring_critical`](circuit_ring_critical.rs) | An all-pass ring's coupling and radius tuned by L-BFGS-B on the circuit adjoint's gradient until its through port is dark at 1.55 µm | W. Bogaerts et al., Laser Photonics Rev. 6, 47 (2012), [doi:10.1002/lpor.201100017](https://doi.org/10.1002/lpor.201100017), Eqs. 2, 3 and 12: on resonance, at critical coupling r = a | 1e-9 µm in the radius, 1e-9 in κ² |
| [`circuit_fit`](circuit_fit.rs) | An add-drop ring's couplings, loss and radius fitted to its through and drop spectra, by L-BFGS-B with the adjoint gradient and by CMA-ES without it, counting evaluations | W. Bogaerts et al. (2012), Eqs. 5 and 6 make the spectra, from known parameters | 1e-8 in κ², 1e-5 dB/cm, 1e-9 µm |
| [`directional_coupler`](directional_coupler.rs) | The cross-over length of two 500 × 220 nm strips 200 nm apart, from their supermodes by the full-vector solver (10 and 5 nm grids, quarter domain), and photonoxide's `DirectionalCoupler` built from them over 1.53–1.57 µm | L. Chrostowski, M. Hochberg, *Silicon Photonics Design* (2015), [doi:10.1017/CBO9781316084168](https://doi.org/10.1017/CBO9781316084168), Section 4.1 and Eq. 4.14: 37.5 µm | 1 µm: their fit to a 10 nm mesh, and our corners (0.4 µm from 10 to 5 nm) |
| [`ring_q_factor`](ring_q_factor.rs) | The ring length that maximizes the loaded Q at critical coupling, all-pass and add-drop, 2.7 dB/cm plus the bends' and couplers' loss, and the ratio of the two peaks; the Q measured on the ring's spectrum beside the formula's | W. Bogaerts et al., Laser Photonics Rev. 6, 47 (2012), [doi:10.1002/lpor.201100017](https://doi.org/10.1002/lpor.201100017), Section 2.4, Eqs. 19–22 and Fig. 5: "approximately 10 mm" and "almost 13 mm", Q 1.42·10⁵ and 1.36·10⁵ | 1 mm and 0.5 mm; 0.0075 in the ratio (three printed digits each) |
| [`mzi_dwivedi`](mzi_dwivedi.rs) | Measured Mach-Zehnder interferometers of 470, 602 and 805 × 211 nm silicon wires in oxide: each wire's mode by Hadley's equations at its SEM cross-section, the interferometers (m = 15 and M = 110) designed for the drawn 215 nm wires, and their spectra read as the paper reads the measured ones, for n_eff and n_g at 1550 nm | S. Dwivedi et al., J. Lightwave Technol. 33, 4471 (2015), [doi:10.1109/JLT.2015.2476603](https://doi.org/10.1109/JLT.2015.2476603), Table I (measured) | the paper's Eq. 5 with ±20 nm of width and ±5 nm of thickness (its Fig. 1), by the solver's derivatives, plus Table I's uncertainty: 0.021 to 0.061 |
**Adding an example:**
- One file per published result. Its doc comment names the paper (with its DOI), the table, figure or page, and how many digits it prints.
- Compare with `common::Checks`, against the paper's numbers as printed. Set the tolerance from the printed digits, or from the paper's stated accuracy.
- Print the grid for every computed number ("exact: no grid" for closed forms).
- Add a row to the table above, and its output to `output/`.
- Print nothing that changes between runs (timings, for instance): the output is compared.
- Make `main` public and add the example to `examples!` in `studio/src-tauri/src/examples.rs`: the
program has every example built in (`photonoxide example <name>`), and the studio runs them.
The full validation report, including analytic and convergence checks, is [docs/validation.md](../docs/validation.md).