# Beam pattern × scene integration
The closed-form beam-broadening width
$\sigma_\mathrm{beam} = |\mathbf{u}_h|\,\theta_b / (2\sqrt{2\ln 2})$
{cite}`DoviakZrnic1993` assumes every scatterer inside the beam sees
the same reflectivity and the same wind — a uniform resolution
volume. When the scene is not uniform (deep convection with
sub-beam-scale reflectivity cells, strong shear across the beam, a
scanning antenna over a horizontally-structured storm), the closed
form breaks and you have to integrate the beam pattern against the
scene explicitly. That is what `rustmatrix.spectra.beam` does.
## What goes wrong with closed-form $\sigma_\mathrm{beam}$
The Doviak–Zrnić result assumes
1. a Gaussian beam pattern $G(\theta)$ of angular full-width-half-
maximum $\theta_b$,
2. a spatially uniform radar reflectivity and PSD inside the beam,
3. a single horizontal wind $\mathbf{u}_h$ across the beam,
and then derives the Doppler-width contribution from the in-beam
distribution of line-of-sight velocities as a closed-form Gaussian.
If any of the three assumptions fails, the measured spectrum is not
$\mathcal{N}(w, \sigma_t^2 + \sigma_\mathrm{beam}^2)$; it's a
$G$-weighted mixture of different reflectivities and velocities. The
[wind × turbulence sensitivity
tutorial](../tutorials/13_wind_turbulence_sensitivity) shows closed-
form $\sigma_\mathrm{beam}$ agreeing with the explicit integration
under uniform conditions; the
[beam × scene tutorial](../tutorials/14_beam_pattern_scene) shows the
case where it fails.
## The integration
For a beam pointing in direction $\hat{\mathbf{n}}$ with angular
pattern $G(\theta)$, and a scene with reflectivity field
$Z(\mathbf{x})$ and wind field $\mathbf{u}(\mathbf{x})$, the received
spectrum at Doppler velocity $v$ is
$$
P(v) = \int G(\theta)^2 \, Z(\mathbf{x}(\theta)) \,
\mathcal{K}\!\left[v - \hat{\mathbf{n}}\cdot\mathbf{u}(\mathbf{x}(\theta))\right]
\, d\Omega,
$$
with $\mathcal{K}$ the turbulence + fall-speed kernel at each beam
angle. `rustmatrix.spectra.beam` discretises the beam angles on a
Gauss–Legendre grid, evaluates the scene at each angle, runs the
per-angle spectrum through `SpectralIntegrator`, and sums weighted
by $G^2$.
## Beam patterns
Two patterns are built in:
* **`GaussianBeam(theta_b, ...)`** — the classic Gaussian analytic
pattern, matched in FWHM to `theta_b`. Sensible default.
* **`AiryBeam(theta_b, ...)`** — the diffraction pattern from a
circular aperture; has non-zero side-lobes.
* **`TabulatedBeam(theta, gain)`** — wrap a measured antenna pattern
as a 1-D (angle, gain) table.
## Scene shortcuts
Building a full 3-D reflectivity + wind scene is tedious. For the
common case of *vertically* pointing radars over a 2-D horizontal
reflectivity map, `spectra.beam` ships helpers:
* `marshall_palmer_scene(Z_map, N0=8000)` — turn a dBZ map into a
per-pixel Marshall–Palmer PSD.
* `convective_cell_scene(...)` — parameterised Gaussian cells for
sensitivity studies; the NB14 tutorial drives an interactive slider
over cell spacing.
## When to reach for this
Use `spectra.beam` when **any** of:
* your beam covers horizontally-structured reflectivity (convective
cells, stratiform-convective transition, the edge of a storm);
* you have strong shear across the beam (upper-level jets, gust
fronts, scanning geometries with large azimuth steps);
* you need to reproduce a measured antenna side-lobe contamination
signature.
For uniform stratiform rain with a narrow beam, the closed-form
$\sigma_\mathrm{beam}$ in `SpectralIntegrator` is faster and
sufficient.
## Further reading
* [NB13 — wind × turbulence sensitivity](../tutorials/13_wind_turbulence_sensitivity)
validates the closed form against explicit integration in its
regime of validity.
* [NB14 — beam × scene](../tutorials/14_beam_pattern_scene) shows the
breakdown in convective scenes.
* {cite}`DoviakZrnic1993`, chapter 7 — for the beam-pattern
mathematics behind the implementation.
```{bibliography}
:filter: docname in docnames
```