feat: PML, facet-bilinear & port boundary operators (+ examples)

[NicolasCayuela]

feat: open-domain wave FEM — PML, facet-bilinear & port boundary operators (+ examples)

Summary

Frequency-domain wave problems (acoustics, 2D optics) need two things the
library didn't have yet: a PML, and a way to
assemble boundary bilinear forms (Robin / impedance / plane-wave ports).
This PR adds both as small, composable pieces on top of the existing
complex-valued assembly, plus two worked examples.

Everything is scalar-Helmholtz, reuses ElementAssembler / SparseMatrix, and
adds no heavy dependencies.

What's added

Assemblers (tensormesh.assemble.builtin, …facet_bilinear)

• AnisotropicLaplaceElementAssembler — tensor-coefficient stiffness
  $\int (\mathbf A,\nabla u)\cdot\nabla v$, complex A supported.
• ScaledMassElementAssembler — coefficient mass $\int c,N_i N_j$.
• FacetBilinearAssembler — boundary bilinear form
  $\int_\Gamma c,N_i N_j,\mathrm dS$ scattered to a SparseMatrix
  (the bilinear counterpart of FacetAssembler, which only does linear forms).

Helpers (tensormesh.pml, tensormesh.bc)

• cartesian_pml — stretched-coordinate PML tensor $\mathbf\Lambda$ + mass
  scaling $s_\text{prod}$ for a rectangular frame.
• robin_operator / port_source — first-order absorbing / plane-wave-port
  boundary matrix and incident load.

Examples using the new operators (examples/wave/)

• helmholtz_resonator/ — port-driven 2D acoustic resonator (uses the port
  operators).
• optical_ring_resonator/ — waveguide-coupled Si microdisk with a PML frame
  (2D TM, whispering-gallery mode); now ships a setup figure showing the
  materials, the line-current launch and the PML boundary.

Additional modal-analysis examples

These reuse the existing builtin assemblers (Laplace / Mass / ScaledMass /
LinearElasticity) with a SciPy generalized-eigenvalue solve — they do not use
the new PML / port operators, but round out the wave / vibration example set and
each validates against a closed-form reference.

• examples/solid/beam_vibration_analysis/ — free-vibration eigenmodes of a
  clamped-free steel cylinder (3D elasticity, consistent vector mass); 3D
  deformed mode-shape gallery, checked vs the Euler-Bernoulli bending
  frequencies.
• examples/wave/wave_guide_mode/ — scalar mode analysis of a rectangular
  dielectric waveguide, $(K - k_0^2 M_\varepsilon)E = -\beta^2 M E$ built from
  Laplace + Mass + ScaledMassElementAssembler; guided $E_{pq}$ field gallery,
  checked vs the separable Marcatili slab approximation.

Validation

Each piece is checked against an analytic or known-good reference:

Piece	Check	Result
AnisotropicLaplace (A = I)	vs LaplaceElementAssembler	max diff 0.0
FacetBilinear boundary mass	$\int_\Gamma 1,\mathrm dS$ = edge length / perimeter	exact
cartesian_pml	point source vs 2D Hankel Green function	corr 0.994
robin_operator / port_source	plane-wave port vs $e^{-ikx}$	corr 0.98
Helmholtz example	fundamental resonance	357 Hz, cavity gain ~12x
Optical example	on-resonance disk field	clean rim WGM
Beam vibration example	1st bending vs Euler-Bernoulli	37.2 vs 36.2 Hz (P1-tet, ~+3%)
Waveguide example	$E_{pq}$ effective indices vs Marcatili	agree to ~$10^{-4}$

Unit tests live in tests/assemble/test_wave.py (13 tests, all passing) and
assert the assembly-level identities above: A = I ⇒ Laplace, c = 1 ⇒ Mass,
boundary mass = perimeter / edge length, the PML stretch tensor, and the Robin /
port boundary mass and load (real and complex coefficients).

Helmholtz resonator

Port-driven duct with a necked side cavity; input impedance over a sweep and the
pressure field at resonance.

Optical ring resonator (waveguide-coupled microdisk)

On resonance the disk lights up in a whispering-gallery mode (bright rim, the
waveguide depleted); the PML frame absorbs the radiated field.

Beam vibration (cantilever cylinder)

Free-vibration mode shapes: bending pairs (circular section ⇒ two planes), first
torsion and first axial mode.

Rectangular waveguide modes

The guided $E_{pq}$ transverse fields of a rectangular dielectric core.

Notes

• The boundary matrix from robin_operator has a boundary-only sparsity pattern,
  so it's folded onto the volume layout before adding (SparseMatrix.__add__
  needs matching layouts). A native cross-layout add would remove the fold — happy
  to do it as a follow-up.
• The port BC is first-order absorbing (some reflection at grazing incidence);
  the PML is the higher-quality absorber for open domains.
• Example figures are git-ignored (examples/**/*.png); they regenerate by
  running each script.
• Follow-ups: rewrite the optical example on top of cartesian_pml +
  AnisotropicLaplace (currently an inline per-quadrature assembler for sharper
  interfaces); 3D PML.

Checklist

• Conventional Commits, DCO Signed-off-by
• NumPy-style docstrings on public API
• No numpy in forward(); complex-safe
• Unit tests under tests/ — tests/assemble/test_wave.py, 13 tests, all passing

[Shizheng-Wen]

Thanks Nicolas — this is exactly the missing piece for open-domain wave problems, and the validation table is a pleasure to review. Landing it ahead of the next release.

Maintainer housekeeping I pushed to your branch (hope you don't mind):

1. Rebased onto current main — the mixed-assembly work (feat(assemble): mixed multi-field block assembly + generalized order pairs #38/feat: mixed multi-field assembly, Taylor-Hood fluid examples, and the matching docs/i18n sync #46) had moved the import blocks in tensormesh/__init__.py etc.; one trivial conflict resolved, your ten commits are otherwise untouched.
2. Namespace homes (top-level API unchanged — tensormesh.robin_operator / port_source / cartesian_pml work exactly as in your examples): tensormesh/bc.py → tensormesh/operator/boundary.py (with the other boundary operators — Condenser, BlochReducer), and tensormesh/pml.py → tensormesh/functional/pml.py (a coefficient-field builder, like the rest of functional).
3. Small dtype fix: robin_operator now derives a scalar coefficient's dtype from the mesh points (float64 mesh → complex128/float64) instead of torch's float32 default.

Docs (API entries + gallery pages for the four examples) will follow in a separate PR on our side. Follow-ups we'd welcome anytime: the cross-layout SparseMatrix.__add__ you noted, an autograd check through robin_operator/PML (the metamaterial-TopOpt adjoint path), and porting transmission_slab.py onto the new public operators.