# Sources and detectors

A source specifies both a spatial field pattern and a temporal signal. A detector reduces the evolving state to data useful after—or during—the run.

## Temporal profiles

`WaveCharacter` accepts exactly one of free-space wavelength, frequency, or period. Source classes can use continuous-wave, Gaussian-windowed, or custom time profiles. Broadband pulses cover multiple frequencies in one run, but every requested phasor still needs sufficient cycles and a clean accumulation window.

Validated temporal behavior includes continuous and Gaussian profiles, custom profiles, pulsed-versus-CW transmission, and dispersive-source correction.

## Spatial excitation

- `PointDipoleSource` injects a localized electric current.
- `UniformPlaneSource` injects a linearly polarized plane field over a finite plane.
- `GaussianPlaneSource` adds a transverse Gaussian amplitude and phase profile.
- `ModePlaneSource` injects a computed cross-sectional eigenmode.
- TFSF sources bound a total-field region and cancel the incident field outside it.

```{figure} ../_static/generated/tfsf.svg
:alt: Total-field scattered-field source enclosing a scatterer

TFSF injection is especially useful when scattered power must be measured without subtracting a large incident field numerically.
```

## Detector choices

| Detector | Produces | Use it for |
|---|---|---|
| `FieldDetector` | sampled $E$/$H$ in space and time | animations, transients, custom reductions |
| `PhasorDetector` | complex frequency-domain fields | phase, impedance, standing waves |
| `PoyntingFluxDetector` | integrated instantaneous power flow | pulse energy and time-domain diagnostics |
| `PhasorPoyntingFluxDetector` | frequency-resolved complex power | spectra and $R/T$ |
| `ModeOverlapDetector` | complex modal amplitudes | port transmission, reflection, and S-parameters |
| `EnergyDetector` | electromagnetic energy | decay and stability checks |

## Sign and normalization

For phasors, the time-average Poynting vector is

$$
\langle\mathbf S\rangle=\frac12\operatorname{Re}\left(\mathbf E\times\mathbf H^*\right).
$$

Detector face orientation determines the sign. For scattering parameters, normalize output mode power by an incident-mode calibration produced with the same source, grid, accumulation convention, and reference plane. The benchmark suite checks phasor/time-domain consistency and passive-power bounds precisely because normalization bugs can otherwise look like excellent device performance.