cavsim2d 0.1.0__py3-none-any.whl

cavsim2d/__init__.py

@@ -0,0 +1,83 @@
+"""
+cavsim2d - 2D axisymmetric RF cavity simulation toolkit.
+
+Main entry points:
+    Study              - Container for multiple Cavity objects
+    EllipticalCavity   - Standard elliptical cavity
+    EllipticalCavityFlatTop - Flat-top elliptical cavity
+    SplineCavity       - Spline-based cavity
+    RFGun              - RF gun cavity
+    Pillbox            - Pillbox cavity
+    Beampipe           - Straight circular beam pipe (drift element)
+    Bellows            - Corrugated bellows section
+    BLA                - Beam line absorber (pipe + lossy ring)
+    Taper              - Conical transition between two bore radii
+    Assembly           - Several devices concatenated into one beam line
+
+Solver objects (attached as lazy properties on Cavity/Study):
+    cav.tune           - TuneSolver
+    cav.eigenmode      - EigenmodeSolver
+    cav.wakefield      - WakefieldSolver
+    cavs.optimisation  - OptimisationSolver
+"""
+__version__ = '0.1.0'
+
+from cavsim2d.models import (
+    Cavity,
+    EllipticalCavity,
+    EllipticalCavityFlatTop,
+    SplineCavity,
+    RFGun,
+    Pillbox,
+    Beampipe,
+    Bellows,
+    BLA,
+    Taper,
+    Assembly,
+    CircularWaveguide,
+)
+from cavsim2d.study import Study
+from cavsim2d.data_module.operating_points import OperationPoints
+from cavsim2d.utils.welcome import show_welcome
+
+from cavsim2d.solvers import (
+    TuneSolver,
+    EigenmodeSolver,
+    WakefieldSolver,
+    OptimisationSolver,
+    EigenmodeResult,
+)
+
+from cavsim2d.utils.style import apply_style, house_style, WARM
+from cavsim2d.analysis.uq import (plot_uq_comparison, uq_comparison_table,
+                                  perturbation_slots, perturbation_nodes)
+
+__all__ = [
+    'Study',
+    'Cavity',
+    'EllipticalCavity',
+    'EllipticalCavityFlatTop',
+    'SplineCavity',
+    'RFGun',
+    'Pillbox',
+    'Beampipe',
+    'Bellows',
+    'BLA',
+    'Taper',
+    'Assembly',
+    'OperationPoints',
+    'show_welcome',
+    'CircularWaveguide',
+    'TuneSolver',
+    'EigenmodeSolver',
+    'WakefieldSolver',
+    'OptimisationSolver',
+    'EigenmodeResult',
+    'apply_style',
+    'house_style',
+    'WARM',
+    'plot_uq_comparison',
+    'uq_comparison_table',
+    'perturbation_slots',
+    'perturbation_nodes',
+]

cavsim2d/analysis/impedance.py

@@ -0,0 +1,366 @@
+"""Impedance reconstructed from eigenmode results (equivalent-circuit model).
+
+Each resonant mode is treated as a parallel RLC resonator, so a handful of
+eigenmode quantities — the resonant frequency, the R/Q and the Q — reproduce the
+impedance spectrum the beam sees around those resonances::
+
+    Z(f) = sum_i  R_i / (1 + i Q_i (f/f_i - f_i/f))          [Ohm]
+
+with the shunt impedance ``R = 1/2 Q (R/Q)``.
+
+This is a *reconstruction*, not a wakefield simulation: it contains exactly the
+modes that were solved for and nothing else — no broadband/resistive-wall
+contribution, and nothing above the highest computed mode. Within that range it
+is cheap, has no wake-length truncation, and lets an eigenmode result be compared
+directly against a beam spectrum or against a wakefield solve (the frames use the
+same columns as ``cav.wakefield.wake_z`` / ``wake_t``).
+
+The cavity is axisymmetric, so the two transverse planes are degenerate — a
+single transverse R/Q describes both, and the x/y average collapses to it.
+"""
+import re
+
+import numpy as np
+import pandas as pd
+
+from cavsim2d.constants import c0
+
+C0 = c0                 # speed of light [m/s]
+
+# Impedance is quoted in kOhm as often as Ohm, so the unit is an argument rather
+# than a convention to memorise: '' = Ohm, 'k' = kOhm, 'M' = MOhm, 'G' = GOhm
+# (per metre for the transverse impedance).
+SI_PREFIXES = {'': 1.0, 'k': 1e3, 'M': 1e6, 'G': 1e9}
+
+# The unit the wakefield backends store their impedance in (ABCI's native kOhm).
+# The eigenmode reconstruction is computed in SI Ohm and converted on the way out,
+# so both end up in the same default unit.
+NATIVE_Z_UNIT = 'k'
+
+
+def prefix_factor(unit):
+    """``(divisor, prefix)`` for an SI prefix. ``'k'`` -> ``(1e3, 'k')``."""
+    u = '' if unit in (None, 'Ohm', 'ohm') else str(unit)
+    if u not in SI_PREFIXES:
+        raise ValueError(
+            f"unknown unit prefix {unit!r}; use one of {sorted(SI_PREFIXES)} "
+            f"— '' for Ohm, 'k' for kOhm, 'M' for MOhm.")
+    return SI_PREFIXES[u], u
+
+
+def impedance_unit(unit, transverse=False):
+    """Column/axis unit string, e.g. ``'kOhm'`` or ``'kOhm/m'``."""
+    _, u = prefix_factor(unit)
+    return f'{u}Ohm/m' if transverse else f'{u}Ohm'
+
+
+def frame_unit(df, default=None):
+    """The SI prefix a frame *declares* in its ``|Z|`` column.
+
+    ``'|Z| [kOhm]'`` -> ``'k'``, ``'|Z| [Ohm/m]'`` -> ``''``. Read the unit from
+    the data rather than assuming a backend's convention: a backend that reports
+    in Ohm and one that reports in kOhm then both convert correctly.
+    """
+    if df is None or df.empty:
+        return NATIVE_Z_UNIT if default is None else default
+    col = next((c for c in df.columns if c.startswith('|Z|')), None)
+    if col is None:
+        return NATIVE_Z_UNIT if default is None else default
+    match = re.search(r'\[([kMG]?)Ohm', col)
+    return match.group(1) if match else (NATIVE_Z_UNIT if default is None else default)
+
+
+def convert_impedance_frame(df, from_unit, to_unit, transverse=False):
+    """Rescale and relabel the ``|Z|``/``Re(Z)``/``Im(Z)`` columns of a frame.
+
+    Columns are matched on their stem, so this works whatever prefix the source
+    frame declares. Other columns (``f [MHz]``, ``s [m]``, ``W``) pass through.
+    """
+    if df is None or df.empty:
+        return df
+    f_from, _ = prefix_factor(from_unit)
+    f_to, _ = prefix_factor(to_unit)
+    if f_from == f_to:
+        return df
+    ratio = f_from / f_to
+    label = impedance_unit(to_unit, transverse)
+
+    out = df.copy()
+    renames = {}
+    for stem in ('|Z|', 'Re(Z)', 'Im(Z)'):
+        col = next((c for c in out.columns if c.startswith(stem)), None)
+        if col is None:
+            continue
+        out[col] = out[col] * ratio
+        renames[col] = f'{stem} [{label}]'
+    return out.rename(columns=renames)
+
+
+def impedance_frame(f_mhz, z, unit='k', transverse=False):
+    """Standard impedance frame from a complex spectrum *z* in **Ohm** (SI)."""
+    factor, _ = prefix_factor(unit)
+    label = impedance_unit(unit, transverse)
+    return pd.DataFrame({
+        'f [MHz]': f_mhz,
+        f'|Z| [{label}]': np.abs(z) / factor,
+        f'Re(Z) [{label}]': z.real / factor,
+        f'Im(Z) [{label}]': z.imag / factor,
+    })
+
+
+def reconstruct_impedance(freqs, r_over_q, q_factors, f_span, transverse=False):
+    """Sum-of-resonators impedance spectrum. All frequencies in **Hz**.
+
+    Parameters
+    ----------
+    freqs : array-like
+        Resonant frequency of each mode [Hz].
+    r_over_q : array-like
+        R/Q of each mode [Ohm]. Longitudinal for ``transverse=False``; for
+        ``transverse=True`` this is the transverse (Panofsky-Wenzel) R/Q, also
+        in Ohm — the ``omega/c`` factor below turns it into Ohm/m.
+    q_factors : array-like
+        Quality factor of each mode. Pass the *loaded* Q if that is what the
+        beam sees; the eigenmode solver reports the unloaded Q0.
+    f_span : array-like
+        Frequencies to evaluate the spectrum at [Hz]. ``f = 0`` is allowed and
+        is evaluated by its limit.
+    transverse : bool
+        Transverse (dipole) impedance [Ohm/m] instead of longitudinal [Ohm].
+
+    Returns
+    -------
+    ndarray of complex
+        The impedance at each frequency in *f_span*: Ohm (longitudinal) or
+        Ohm/m (transverse).
+    """
+    f0 = np.asarray(freqs, dtype=float)
+    roq = np.asarray(r_over_q, dtype=float)
+    q = np.asarray(q_factors, dtype=float)
+    f = np.asarray(f_span, dtype=float)
+
+    if not (f0.shape == roq.shape == q.shape):
+        raise ValueError(f"freqs, r_over_q and q_factors must have the same length; "
+                         f"got {f0.shape}, {roq.shape}, {q.shape}.")
+    if np.any(f0 <= 0):
+        raise ValueError("mode frequencies must be positive.")
+
+    # Shunt impedance of each resonator. The transverse case picks up omega_0/c,
+    # which is what converts a transverse R/Q [Ohm] into a shunt impedance [Ohm/m].
+    r_shunt = 0.5 * q * roq
+    if transverse:
+        r_shunt = r_shunt * (2 * np.pi * f0 / C0)
+
+    z = np.zeros(f.shape, dtype=complex)
+    live = f > 0                      # f = 0 is singular in the resonator term
+    f_live = f[live]
+
+    for fi, ri, qi in zip(f0, r_shunt, q):
+        # Breit-Wigner resonator: 1 + i Q (f/f0 - f0/f)
+        denom = 1 + 1j * qi * (f_live / fi - fi / f_live)
+        term = ri / denom
+        if transverse:
+            term = term * (fi / f_live)
+        z[live] += term
+
+    if not live.all():
+        # DC limit. denom -> -i Q f0/f as f -> 0, so the longitudinal term tends
+        # to 0 while the transverse term tends to R/(-iQ) = i R/Q (finite).
+        z[~live] = np.sum(1j * r_shunt / q) if transverse else 0.0
+
+    return z
+
+
+def reconstruct_impedance_qnm(freqs, r_over_q_complex, q_factors, f_span,
+                              transverse=False):
+    """Pole-expansion impedance from **complex** mode residues. Frequencies in Hz.
+
+    :func:`reconstruct_impedance` gives every mode a positive-real shunt impedance,
+    which is exact for an isolated resonance and wrong for overlapping ones: it makes
+    neighbouring poles add in phase. Above a beam-pipe cutoff, where radiating modes
+    have Q of order 10 and linewidths wider than the mode spacing, that coherent
+    addition overestimates ``|Z|`` by roughly the number of modes overlapping at each
+    frequency.
+
+    .. warning::
+       **Experimental, and currently not validated on radiating modes.** The residue
+       *magnitudes* are exact — ``|(R/Q)~|`` reproduces ``R/Q`` to machine precision —
+       but their *phases* do not yet come out physical: on a PML solve of a TESLA
+       3-cell the resulting spectrum violates passivity (``Re Z < 0``) over most of
+       the band above cutoff, and is further from a wakefield reference than the plain
+       RLC sum. Correct QNM normalisation of a PML eigenvector needs more than the
+       unconjugated volume integral used here. Treat the output as a diagnostic, not
+       as an impedance. Above the cutoff the reliable route today is to filter the
+       mode set with :func:`pml_stable_modes` and sum it with
+       :func:`reconstruct_impedance`.
+
+    This builds the same spectrum from the quasi-normal-mode residues instead. With
+    ``w~ = w(1 - i/2Q)`` the decaying complex eigenfrequency and ``a~ = w~ (R/Q)~ / 2``
+    the wake amplitude, the wake ``W(t) = Re[a~ exp(-i w~ t)]`` transforms to::
+
+        Z(w) = (i/2) sum_n [ a~_n / (w - w~_n)  +  conj(a~_n) / (w + conj(w~_n)) ]
+
+    The conjugate-pole partner is what enforces ``Z(-w) = conj(Z(w))``, i.e. a real
+    wake. For a real ``(R/Q)~`` and large Q this reduces term by term to the RLC form,
+    peaking at ``1/2 Q (R/Q)``.
+
+    Parameters
+    ----------
+    freqs : array-like
+        Real part of each mode frequency [Hz].
+    r_over_q_complex : array-like of complex
+        ``(R/Q)~ = V~^2 / (w~ U~)`` per mode [Ohm] — the solver's
+        ``'Re(R/Q) [Ohm]'`` + 1j*``'Im(R/Q) [Ohm]'``.
+    q_factors : array-like
+        Quality factor of each mode.
+    f_span : array-like
+        Frequencies to evaluate at [Hz]. ``f = 0`` is evaluated by its limit.
+    transverse : bool
+        Transverse impedance [Ohm/m], using the same ``w_0/c`` and ``w_0/w``
+        convention as :func:`reconstruct_impedance`.
+
+    Returns
+    -------
+    ndarray of complex
+    """
+    f0 = np.asarray(freqs, dtype=float)
+    roq = np.asarray(r_over_q_complex, dtype=complex)
+    q = np.asarray(q_factors, dtype=float)
+    f = np.asarray(f_span, dtype=float)
+
+    if not (f0.shape == roq.shape == q.shape):
+        raise ValueError(f"freqs, r_over_q_complex and q_factors must have the same "
+                         f"length; got {f0.shape}, {roq.shape}, {q.shape}.")
+    if np.any(f0 <= 0):
+        raise ValueError("mode frequencies must be positive.")
+
+    w0 = 2 * np.pi * f0
+    w = 2 * np.pi * f
+    z = np.zeros(f.shape, dtype=complex)
+
+    for w0i, roqi, qi in zip(w0, roq, q):
+        w_c = w0i * (1 - 0.5j / max(abs(qi), 1e-30))     # decaying pole
+        a_c = w_c * roqi / 2                             # wake amplitude
+        term = 0.5j * (a_c / (w - w_c) + np.conj(a_c) / (w + np.conj(w_c)))
+        if transverse:
+            # Same convention as the RLC path: R/Q_t [Ohm] -> Ohm/m via w_0/c, and
+            # the extra w_0/w that makes the transverse resonance peak at w_0.
+            with np.errstate(divide='ignore', invalid='ignore'):
+                term = term * (w0i / C0) * np.where(w > 0, w0i / np.where(w > 0, w, 1), 0.0)
+        z += term
+
+    return z
+
+
+def classify_modes(modes, other, rtol_f=2e-4, linewidth_frac=0.02, rtol_q=0.25,
+                   pair_frac=0.1, runner_up=3.0):
+    """Cavity mode or artefact, for each mode of an open solve, from a second solve.
+
+    An open (PML) solve returns genuine resonances of the cavity mixed with modes of
+    the beam pipe and of the absorbing block, and they look alike in the results.
+    Re-solving with a different ``beampipe_length`` (or ``pml_length``) separates
+    them: a cavity mode does not care how long the pipe is, a pipe mode moves. This
+    is the best discriminant found so far, and it is not perfect. On pillbox and
+    TESLA test cases it miscounts a few per cent of the modes, in both directions.
+
+    Each mode of *modes* is judged against *other*, per azimuthal order ``m``:
+
+    1. Frequency, the primary test. Its partner must be its mutual nearest neighbour
+       (each is the other's closest mode), within ``max(rtol_f, linewidth_frac / Q)``
+       relative. The tolerance scales with the linewidth ``f/Q``: a broad radiating
+       mode moves by a larger fraction than a narrow one for the same physical
+       change. A partner is ambiguous, and rejected, when a runner-up sits within
+       the tolerance and less than ``runner_up`` times further away.
+    2. Q, a tie-breaker only. A mode whose Q moved by more than ``rtol_q`` is still
+       kept, since the Q of a mode near the cutoff converges slowly with pipe length
+       (the layer keeps reaching its evanescent tail). It is dropped only when it
+       also has a near-degenerate partner of the same ``m``, closer than
+       ``pair_frac`` of the typical spacing. At fixed ``m`` an axisymmetric cavity
+       has no degeneracy, so such a pair is the left and right pipe, not one mode.
+
+    Parameters
+    ----------
+    modes, other : pandas.DataFrame
+        Two ``cav.eigenmode.qois_df`` frames of the same cavity, solved with a
+        different pipe (or PML) length. Needs ``'freq [MHz]'`` and ``'Q []'``;
+        ``'m'`` is used when present.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Indexed like *modes*: ``'cavity mode'`` (the verdict), and the evidence behind
+        it, ``'shift [ppm]'``, ``'tolerance [ppm]'``, ``'mutual'``, ``'f ok'``,
+        ``'Q ok'``, ``'paired'`` and ``'reached'``.
+
+    Notes
+    -----
+    Compare only where both runs reach. Each solve returns its lowest ``n_modes``,
+    and a mode above *other*'s highest has nothing to be matched against: it comes
+    back ``'reached' == False`` and is not called a cavity mode (unverified, not
+    disproved). Raise ``n_modes`` until both runs cover the band of interest.
+    """
+    out = pd.DataFrame(index=modes.index)
+    for col, default in (('shift [ppm]', np.nan), ('tolerance [ppm]', np.nan),
+                         ('mutual', False), ('f ok', False), ('Q ok', False),
+                         ('paired', False), ('reached', False)):
+        out[col] = default
+
+    def groups(df):
+        if 'm' in df.columns:
+            return {m: g for m, g in df.groupby('m')}
+        return {0: df}
+
+    other_groups = groups(other)
+    for m, a in groups(modes).items():
+        b = other_groups.get(m)
+        f_a = a['freq [MHz]'].to_numpy(dtype=float)
+        q_a = a['Q []'].to_numpy(dtype=float)
+        if b is None or len(b) == 0:
+            continue
+        f_b = b['freq [MHz]'].to_numpy(dtype=float)
+        q_b = b['Q []'].to_numpy(dtype=float)
+
+        rel = np.abs(f_a[:, None] - f_b[None, :]) / f_a[:, None]
+        j = rel.argmin(axis=1)
+        d1 = rel[np.arange(len(f_a)), j]
+        d2 = (np.partition(rel, 1, axis=1)[:, 1] if rel.shape[1] > 1
+              else np.full(len(f_a), np.inf))
+        back = (np.abs(f_b[:, None] - f_a[None, :]) / f_b[:, None]).argmin(axis=1)
+        mutual = back[j] == np.arange(len(f_a))
+        tol = np.maximum(rtol_f, linewidth_frac / np.maximum(np.abs(q_a), 1e-30))
+        ambiguous = (d2 <= tol) & (d2 < runner_up * d1)
+        f_ok = mutual & (d1 <= tol) & ~ambiguous
+        q_ok = np.abs(q_b[j] - q_a) <= rtol_q * np.maximum(np.abs(q_a), 1e-30)
+
+        # near-degenerate partner of the same m, relative to the typical spacing
+        if len(f_a) > 1:
+            gaps = np.abs(f_a[:, None] - f_a[None, :]) / f_a[:, None]
+            np.fill_diagonal(gaps, np.inf)
+            nearest = gaps.min(axis=1)
+            paired = nearest < pair_frac * np.median(nearest)
+        else:
+            paired = np.zeros(len(f_a), dtype=bool)
+
+        idx = a.index
+        out.loc[idx, 'shift [ppm]'] = d1 * 1e6
+        out.loc[idx, 'tolerance [ppm]'] = tol * 1e6
+        out.loc[idx, 'mutual'] = mutual
+        out.loc[idx, 'f ok'] = f_ok
+        out.loc[idx, 'Q ok'] = q_ok
+        out.loc[idx, 'paired'] = paired
+        out.loc[idx, 'reached'] = f_a <= f_b.max() * (1 + rtol_f)
+
+    out['cavity mode'] = (out['f ok'] & ~(~out['Q ok'] & out['paired'])
+                          & out['reached']).astype(bool)
+    return out
+
+
+def pml_stable_modes(modes, other, **kwargs):
+    """Boolean mask over *modes*: the cavity modes, judged against a second solve
+    with a different pipe or PML length. See :func:`classify_modes`, which returns
+    the same verdict with the evidence behind it.
+
+    >>> keep = pml_stable_modes(cav_a.eigenmode.qois_df, cav_b.eigenmode.qois_df)
+    >>> trusted = cav_a.eigenmode.qois_df[keep]
+    """
+    return classify_modes(modes, other, **kwargs)['cavity mode'].to_numpy(dtype=bool)

cavsim2d/analysis/lorentz/__init__.py

@@ -0,0 +1,7 @@
+"""Lorentz radiation pressure, wall deflection and Lorentz detuning."""
+from cavsim2d.analysis.lorentz.pressure import (pressure_cf, wall_pressure,
+                                                stored_energy, slater_shift,
+                                                detuning_coefficient)
+
+__all__ = ['pressure_cf', 'wall_pressure', 'stored_energy', 'slater_shift',
+           'detuning_coefficient']

cavsim2d/analysis/lorentz/pressure.py

@@ -0,0 +1,226 @@
+r"""Lorentz radiation pressure on a cavity wall, and the detuning it causes.
+
+Theory
+------
+The RF field exerts a pressure on the conducting wall. With fields written as peak
+amplitudes the time-averaged energy densities are :math:`u_H=\tfrac14\mu_0|H|^2` and
+:math:`u_E=\tfrac14\varepsilon_0|E|^2`, and the outward pressure is their difference:
+
+.. math::  P = \tfrac14\left(\mu_0|H|^2 - \varepsilon_0|E|^2\right)
+
+so the magnetic field near the equator pushes the wall **out** and the electric field near
+the iris pulls it **in**. On a perfect conductor the tangential electric and normal
+magnetic components vanish, so :math:`|E|` is purely normal there and :math:`|H|` purely
+tangential.
+
+Given a wall displacement :math:`\mathbf{u}`, Slater's theorem gives the frequency shift
+as the work the pressure does against that displacement, normalised by the stored energy:
+
+.. math::  \frac{\Delta\omega}{\omega}
+           = -\frac{1}{U}\oint_S P\,(\mathbf{u}\cdot\mathbf{n})\,\mathrm{d}S
+
+Pushing the wall **in** where the magnetic field is strong raises the frequency; pushing
+it in where the electric field is strong lowers it. The static deflection is itself
+proportional to the pressure, and the pressure to :math:`E_\mathrm{acc}^2`, so the shift
+is quoted as the Lorentz detuning coefficient
+
+.. math::  K_L = \frac{\Delta f}{E_\mathrm{acc}^2}\quad[\mathrm{Hz/(MV/m)^2}]
+
+which is negative for an unstiffened cavity: the inward pull at the iris and the outward
+push at the equator both lower the frequency of the accelerating mode.
+
+Scope
+-----
+The pressure follows from the RF solution with no further modelling. The **displacement
+does not** - it depends on the wall thickness, the elastic constants, and above all on how
+the cavity is held, none of which the RF model knows. :func:`slater_shift` therefore takes
+the displacement as an argument rather than computing it: supply one from a mechanical
+solve and this module turns it into a frequency shift.
+
+Validation
+----------
+A TM010 pillbox has :math:`f = c\,x_{01}/(2\pi R)`, which depends on the radius and not on
+the length. Both identities are reproduced: a uniform outward displacement of the barrel
+gives :math:`\Delta f/f = -\alpha/R` to 0.001%, and the same displacement of the end
+plates gives zero.
+"""
+import numpy as np
+from ngsolve import (Conj, GridFunction, H1, Integrate, InnerProduct, Norm,
+                     VectorH1, specialcf, y)
+
+from cavsim2d.constants import eps0, mu0
+from cavsim2d.solvers.NGSolve.eigen_ngsolve import get_boundary_nodes
+
+__all__ = ['MU0', 'EPS0', 'pressure_cf', 'wall_pressure', 'stored_energy',
+           'slater_shift', 'wall_force', 'detuning_coefficient']
+
+MU0 = mu0
+EPS0 = eps0
+
+
+def _projected_fields(mesh, gfu_E, gfu_H, mode, order):
+    """E and H projected into continuous H1, so their traces integrate on a boundary.
+
+    Two separate reasons, both of which silently corrupt a wall integral:
+
+    * **H** is reconstructed as ``curl(E)/(mu0 w)``, and a GridFunction curl cannot
+      be SIMD-evaluated on a boundary - the integral fails outright with "SIMD:
+      don't know how I shall evaluate".
+    * **E** lives in HCurl, whose boundary trace keeps only the TANGENTIAL part. On
+      a perfect conductor that part is zero by definition, so an unprojected
+      ``|E|^2`` evaluates to nothing on the wall and the electric half of the
+      pressure disappears without any error being raised.
+
+    The eigenmode solver projects H the same way for its wall-loss integral. On a
+    PML mesh the projection is restricted to the physical region: H1 is continuous,
+    so projecting across the interface would average in the complex-stretched
+    layer's own field.
+    """
+    u_gf, uphi_gf = gfu_E[mode].components
+    H_inplane, H_phi = gfu_H[mode]
+    kw = ({'definedon': mesh.Materials('phys')}
+          if 'pml' in mesh.GetMaterials() else {})
+    ein = GridFunction(VectorH1(mesh, order=order, complex=True))
+    ein.Set(u_gf, **kw)
+    hphi = GridFunction(H1(mesh, order=order, complex=True))
+    hphi.Set(H_phi, **kw)
+    hin = GridFunction(VectorH1(mesh, order=order, complex=True))
+    hin.Set(H_inplane, **kw)
+    return ein, uphi_gf, hin, hphi
+
+
+def _field_norms(gfu_E, gfu_H, mode=0, m=0, mesh=None, project=False):
+    """``(|E|^2, |H|^2)`` as coefficient functions.
+
+    A monopole keeps all of E in the in-plane block and all of H in the azimuthal
+    one, so the other terms drop out. The general form is kept because an m>=1 mode
+    populates both.
+
+    Set *project* for a boundary integral; see :func:`_projected_H`.
+    """
+    u_gf, uphi_gf = gfu_E[mode].components
+    if project:
+        u_gf, uphi_gf, H_inplane, H_phi = _projected_fields(
+            mesh, gfu_E, gfu_H, mode, u_gf.space.globalorder)
+        e2 = InnerProduct(u_gf, u_gf)
+        h2 = InnerProduct(H_inplane, H_inplane) + Norm(H_phi) ** 2
+        if m != 0:
+            e2 = e2 + Norm(uphi_gf) ** 2 / (y * y + 1e-30)
+        return e2, h2
+    H_inplane, H_phi = gfu_H[mode]
+    e2 = InnerProduct(u_gf, u_gf)
+    h2 = InnerProduct(H_inplane, H_inplane) + Norm(H_phi) ** 2
+    if m != 0:
+        # E_phi = u_phi / r. The wall reaches the axis only at a beam-pipe end cap,
+        # where u_phi vanishes anyway, so the guard only avoids a 0/0.
+        e2 = e2 + Norm(uphi_gf) ** 2 / (y * y + 1e-30)
+    return e2, h2
+
+
+def _azimuthal_factor(m):
+    """Integral over phi: 2*pi for a monopole, pi for m>=1 (cos^2 averages to 1/2)."""
+    return 2 * np.pi if m == 0 else np.pi
+
+
+def pressure_cf(gfu_E, gfu_H, mode=0, m=0, scale=1.0, mesh=None, project=False):
+    """Lorentz radiation pressure as a coefficient function, in pascals.
+
+    Positive pushes the wall outward (magnetic), negative inward (electric). *scale*
+    multiplies the field amplitude, so the pressure scales with its square - pass the
+    factor that takes the stored solution to the gradient you want.
+    """
+    e2, h2 = _field_norms(gfu_E, gfu_H, mode, m, mesh, project)
+    return 0.25 * (MU0 * h2 - EPS0 * e2) * (scale ** 2)
+
+
+def stored_energy(mesh, gfu_E, gfu_H, mode=0, m=0, eps_cf=None):
+    r"""Total stored energy of the mode, in joules.
+
+    The time-averaged electric and magnetic energies are equal at resonance, so the
+    total is twice either one: :math:`U=\tfrac12\varepsilon_0\int|E|^2\,\mathrm{d}V`.
+    """
+    e2, _ = _field_norms(gfu_E, gfu_H, mode, m)
+    eps = EPS0 if eps_cf is None else EPS0 * eps_cf
+    return float(Integrate(0.5 * eps * e2 * y, mesh).real) * _azimuthal_factor(m)
+
+
+def wall_pressure(mesh, gfu_E, gfu_H, mode=0, m=0, scale=1.0, wall='PEC',
+                  points=None):
+    """Sample the pressure on the wall.
+
+    Parameters
+    ----------
+    points : array_like, optional
+        ``(n, 2)`` array of ``(z, r)`` in metres to evaluate at. Defaults to the
+        mesh's boundary nodes, which are ordered by coordinate rather than along the
+        contour - pass ``profile.contour_points(ds)`` when the samples must follow
+        the wall, as a line plot needs.
+
+    Returns
+    -------
+    (points, p) : ndarray, ndarray
+        Sample coordinates in metres, and the pressure at each in pascals.
+    """
+    cf = pressure_cf(gfu_E, gfu_H, mode, m, scale)
+    if points is None:
+        points = sorted(get_boundary_nodes(mesh, wall))
+    pts = np.asarray(points, dtype=float).reshape(-1, 2)
+    vals = np.asarray(cf(mesh(pts[:, 0], pts[:, 1]))).ravel().real
+    return pts, vals
+
+
+def slater_shift(mesh, gfu_E, gfu_H, normal_displacement, freq_hz,
+                 mode=0, m=0, wall='PEC', scale=1.0, U=None):
+    r"""Frequency shift from a wall displacement, by Slater's theorem, in hertz.
+
+    Parameters
+    ----------
+    normal_displacement : CoefficientFunction
+        The OUTWARD normal component of the wall displacement, in metres. A
+        GridFunction from a mechanical solve is the intended input; an analytic
+        expression built from ``ngsolve.x`` / ``ngsolve.y`` also works.
+    freq_hz : float
+        Unperturbed frequency.
+    U : float, optional
+        Stored energy. Computed from the fields when omitted; pass it to avoid
+        recomputing it across a sweep.
+
+    Returns
+    -------
+    float
+        :math:`\Delta f`, negative when the wall moves so as to lower the frequency,
+        which is the usual sense for an unstiffened cavity.
+
+    Notes
+    -----
+    The mesh is a meridian, so the surface element of the body of revolution carries
+    the factor ``r``, and the azimuthal integral contributes ``2*pi`` (``pi`` for
+    m>=1).
+    """
+    p_cf = pressure_cf(gfu_E, gfu_H, mode, m, scale, mesh, project=True)
+    if U is None:
+        U = stored_energy(mesh, gfu_E, gfu_H, mode, m)
+    work = float(Integrate(p_cf * normal_displacement * y, mesh,
+                           definedon=mesh.Boundaries(wall)).real)
+    return -freq_hz * work * _azimuthal_factor(m) / U
+
+
+def wall_force(mesh, gfu_E, gfu_H, mode=0, m=0, wall='PEC', scale=1.0):
+    """Net force the field exerts on *wall*, as ``(F_z, F_r)`` in newtons.
+
+    A cheap sanity check on the pressure: for a mode symmetric about the mid-plane
+    the axial components cancel, so ``F_z`` should come out near zero.
+    """
+    p_cf = pressure_cf(gfu_E, gfu_H, mode, m, scale, mesh, project=True)
+    n = specialcf.normal(2)
+    az = _azimuthal_factor(m)
+    fz = float(Integrate(p_cf * n[0] * y, mesh,
+                         definedon=mesh.Boundaries(wall)).real) * az
+    fr = float(Integrate(p_cf * n[1] * y, mesh,
+                         definedon=mesh.Boundaries(wall)).real) * az
+    return fz, fr
+
+
+def detuning_coefficient(delta_f_hz, eacc_mv_per_m):
+    r"""Lorentz detuning coefficient :math:`K_L`, in Hz/(MV/m)^2."""
+    return delta_f_hz / (float(eacc_mv_per_m) ** 2)