cavsim2d 0.1.0__py3-none-any.whl

cavsim2d/analysis/multipacting/__init__.py

@@ -0,0 +1,21 @@
+"""Multipacting analysis for 2D-axisymmetric RF cavities.
+
+Relativistic electron tracking in the cavity's eigenmode field with secondary
+emission, following the PyMultipact method (the user's validated physics). The
+EM field is read from a cavsim2d eigenmode result and the whole analysis is
+driven through the ``cav.multipacting`` solver object; this package holds the
+pieces:
+
+- :mod:`.particles` / :mod:`.integrators` -- particle state + RK4 Lorentz push,
+- :mod:`.sey` -- the secondary-emission-yield table,
+- :mod:`.fields` -- the eigenmode-field adapter (in-plane E + reconstructed H),
+- :mod:`.driver` -- the peak-field sweep,
+- :mod:`.metrics` -- counter / final-energy / distance-function metrics.
+
+Only the ngsolve-free pieces (``SEY``) are re-exported here; ``driver``/``fields``
+pull in ngsolve, so import them from their submodules where the field is needed —
+keeping ``import cavsim2d`` soft on the ngsolve dependency.
+"""
+from cavsim2d.analysis.multipacting.sey import SEY, DEFAULT_SEY
+
+__all__ = ['SEY', 'DEFAULT_SEY']

cavsim2d/analysis/multipacting/driver.py

@@ -0,0 +1,487 @@
+"""Multipacting field-level sweep driver.
+
+Ported from PyMultipact's ``Domain.analyse_multipacting`` / ``_analyse_multipacting``,
+reworked so the EM field comes from a cavsim2d eigenmode result folder (the
+adapter in :mod:`.fields`) and everything is written under ``<cav>/multipacting/``.
+
+For each peak-field value in the sweep, an electron cloud is launched from the
+wall over a grid of RF launch phases and tracked with the RK4 integrator; the
+counter function ``c20/c0`` is the fraction that survives to 20 impacts. The
+sweep is embarrassingly parallel over field levels (one worker per chunk).
+"""
+import itertools
+from collections import defaultdict
+import multiprocessing as mp
+import os
+import pickle
+import subprocess
+import sys
+import threading
+import time
+import traceback
+from pathlib import Path
+
+import numpy as np
+from ngsolve import Norm
+from tqdm.auto import tqdm
+
+from cavsim2d.analysis.multipacting.fields import build_emfield, load_eigenmode_fields
+from cavsim2d.constants import c0, m0, q0  # noqa: F401  (re-exported to the workers)
+from cavsim2d.analysis.multipacting.integrators import Integrators
+from cavsim2d.analysis.multipacting.metrics import distance_function
+from cavsim2d.analysis.multipacting.particles import Particles
+from cavsim2d.utils.run_log import RunTimer
+
+
+
+def _surface_polyline(mesh, bc='PEC'):
+    """Wall (PEC) vertices in CONTOUR order, with a chain id per vertex.
+
+    The wall is walked along its boundary elements, so consecutive points are
+    neighbours on the wall, and each chain is oriented with the vacuum on its right:
+    the collision code takes a segment's right-hand normal as the inward normal.
+    Separate pieces of wall (chains) get separate ids and are never joined.
+
+    The points used to be sorted by z. That orders a wall correctly only while z
+    increases along it. A wall that turns back in z (a re-entrant iris, an RF gun's
+    funnel) or runs down a vertical face (a pillbox's right-hand plate) was then
+    joined out of order, into segments that cross the vacuum, and the normals of
+    an overhanging wall pointed into the metal.
+    """
+    adj = defaultdict(set)
+    for el in mesh.Boundaries(bc).Elements():
+        vs = [v.nr for v in el.vertices]
+        if len(vs) >= 2 and vs[0] != vs[-1]:
+            adj[vs[0]].add(vs[-1])
+            adj[vs[-1]].add(vs[0])
+    pos = {v: tuple(mesh.vertices[v].point) for v in adj}
+    unseen = set(adj)
+    chains = []
+    while unseen:
+        ends = [v for v in unseen if len(adj[v] & unseen) <= 1]
+        cur = min(ends or unseen, key=lambda v: pos[v])
+        chain = [cur]
+        unseen.discard(cur)
+        while True:
+            nxt = sorted((w for w in adj[cur] if w in unseen), key=lambda w: pos[w])
+            if not nxt:
+                break
+            cur = nxt[0]
+            chain.append(cur)
+            unseen.discard(cur)
+        pts = np.array([pos[v] for v in chain], dtype=float)
+        if len(pts) >= 2 and not _vacuum_on_right(mesh, pts):
+            pts = pts[::-1]
+        chains.append(pts)
+    chains.sort(key=lambda c: (c[:, 0].min(), c[:, 1].min()))
+    points = np.vstack(chains) if chains else np.empty((0, 2))
+    chain_id = np.concatenate([np.full(len(c), i) for i, c in enumerate(chains)]) \
+        if chains else np.empty(0, dtype=int)
+    return points, chain_id
+
+
+def _vacuum_on_right(mesh, pts):
+    """True if the meshed region lies to the right of the polyline *pts*, tested a
+    fraction of a segment length off the longest segment's midpoint."""
+    d = np.diff(pts, axis=0)
+    k = int(np.argmax(np.hypot(d[:, 0], d[:, 1])))
+    mid = 0.5 * (pts[k] + pts[k + 1])
+    length = float(np.hypot(*d[k]))
+    right = np.array([d[k][1], -d[k][0]]) / length
+    probe = mid + 0.05 * length * right
+    return mesh(float(probe[0]), float(probe[1])).nr >= 0
+
+
+def _surface_points(mesh, bc='PEC'):
+    """Wall (PEC) vertices in contour order -- the emission sites and the collision
+    polyline (see :func:`_surface_polyline`). cavsim2d names the cavity wall 'PEC'
+    (PyMultipact used 'default')."""
+    return _surface_polyline(mesh, bc)[0]
+
+
+def _bounding_rect(xsurf):
+    z, r = xsurf[:, 0], xsurf[:, 1]
+    return [float(z.min()), float(z.max()), float(r.min()), float(r.max())]
+
+
+def default_xrange(xsurf):
+    """Default emission band: a few wall points around the equator (the
+    max-radius point), where elliptical-cavity multipacting concentrates. Spans
+    the nearest wall points so the band always contains emission sites (an
+    empty band makes the ported Particles call exit())."""
+    z = xsurf[:, 0]
+    z_eq = float(z[np.argmax(xsurf[:, 1])])
+    near = np.sort(np.abs(z - z_eq))[:min(7, len(z))]
+    half = max(float(near.max()), 0.5e-3) + 1e-9
+    return [z_eq - half, z_eq + half]
+
+
+def densify_wall(xsurf, xrange, n_points, chain=None):
+    """Insert extra vertices along the wall polyline inside *xrange* so the band
+    carries about ``n_points`` emission sites — WITHOUT refining the mesh.
+
+    Emission sites are wall-polyline vertices, so a coarse mesh offers only a
+    handful in a narrow band. The wall between two consecutive vertices is a
+    straight segment (the tracker's collision polyline is straight by
+    construction), so points interpolated along it lie exactly on the wall: the
+    polyline — and hence the collision geometry and the surface normals — is
+    unchanged, there are simply more places to launch from. Cheaper and far more
+    local than shrinking ``pec_maxh`` over the whole cavity.
+
+    *xsurf* is in contour order (see :func:`_surface_polyline`), and each stretch
+    of wall crossing the band is resampled along its own arclength, in place, so
+    the order survives. *chain* is the chain id per point; when given, the result
+    is ``(points, chain)``, otherwise just the points. ``n_points`` at or below the
+    number already present is a no-op.
+    """
+    xsurf = np.asarray(xsurf, dtype=float)
+    ids = np.zeros(len(xsurf), dtype=int) if chain is None else np.asarray(chain)
+
+    def done(pts, cid):
+        return pts if chain is None else (pts, cid)
+
+    n_points = int(n_points or 0)
+    if n_points <= 0 or len(xsurf) < 2:
+        return done(xsurf, ids)
+    lo, hi = float(xrange[0]), float(xrange[1])
+    z = xsurf[:, 0]
+    inb = (z >= lo) & (z <= hi)
+    if n_points <= int(inb.sum()):
+        return done(xsurf, ids)            # already at least that many sites
+
+    # segments (i, i+1) of one chain whose z-span meets the band, grouped into runs
+    seg = [i for i in range(len(xsurf) - 1)
+           if ids[i] == ids[i + 1] and min(z[i], z[i + 1]) <= hi and max(z[i], z[i + 1]) >= lo]
+    runs = []
+    for i in seg:
+        if runs and runs[-1][-1] == i - 1:
+            runs[-1].append(i)
+        else:
+            runs.append([i])
+    if not runs:
+        return done(xsurf, ids)
+
+    def _resample(pts, n):
+        d = np.r_[0.0, np.cumsum(np.hypot(*np.diff(pts, axis=0).T))]
+        if d[-1] <= 0:
+            return None
+        t = np.linspace(0.0, d[-1], int(n))
+        return np.column_stack([np.interp(t, d, pts[:, 0]),
+                                np.interp(t, d, pts[:, 1])])
+
+    out_pts, out_ids, cursor = [], [], 0
+    for run in runs:
+        a, b = run[0], run[-1] + 1                     # points a..b span the run
+        stretch = xsurf[a:b + 1]
+        fine = _resample(stretch, max(n_points * 8, 64))
+        cand = None if fine is None else fine[(fine[:, 0] >= lo) & (fine[:, 0] <= hi)]
+        dense = _resample(cand, n_points) if cand is not None and len(cand) >= 2 else None
+        if dense is None:
+            continue
+        keep = ~inb[a:b + 1]
+        first_in = int(np.argmax(~keep)) if (~keep).any() else None
+        before = [p for j, p in enumerate(stretch) if keep[j] and (first_in is None or j < first_in)]
+        after = [p for j, p in enumerate(stretch) if keep[j] and first_in is not None and j > first_in]
+        if first_in is None:                            # no vertex inside: split by arclength
+            before, after = [stretch[0]], [stretch[-1]]
+        out_pts.append(xsurf[cursor:a])
+        out_ids.append(ids[cursor:a])
+        new = np.vstack([np.array(before).reshape(-1, 2), dense, np.array(after).reshape(-1, 2)])
+        out_pts.append(new)
+        out_ids.append(np.full(len(new), ids[a]))
+        cursor = b + 1
+    out_pts.append(xsurf[cursor:])
+    out_ids.append(ids[cursor:])
+    return done(np.vstack(out_pts), np.concatenate(out_ids))
+
+
+def _peak_surface_field(em, mesh, xsurf):
+    """Peak in-plane |E| over the interior wall points (drives the Epk
+    normalisation)."""
+    zmin, zmax = xsurf[:, 0].min(), xsurf[:, 0].max()
+    interior = xsurf[(xsurf[:, 1] > 0) & (xsurf[:, 0] > zmin) & (xsurf[:, 0] < zmax)]
+    esurf = [Norm(em.e)(mesh(float(zi), float(ri))) for (zi, ri) in interior]
+    return float(max(esurf))
+
+
+def _worker(proc_id, folder, fields_dir, freq_mode, mode, xrange, procs_epks,
+            phis, v_init, sey, Epk, step, bounding_rect, loss_model, t_max,
+            n_points=None):
+    """One process's slice of the Epk sweep. Reloads the mesh + eigenmode field
+    from *fields_dir*, builds the multipacting EM field, and tracks the cloud for
+    each assigned peak-field value; writes ``mresults_{proc_id}``.
+
+    Any failure is written to ``mresults_{proc_id}.err`` — a spawned child's
+    stderr is invisible in notebooks, so the traceback must reach a file the
+    parent can read back. BaseException also catches the ``exit()`` the ported
+    Particles code calls on an empty emission set (SystemExit)."""
+    try:
+        _worker_impl(proc_id, folder, fields_dir, freq_mode, mode, xrange,
+                     procs_epks, phis, v_init, sey, Epk, step, bounding_rect,
+                     loss_model, t_max, n_points)
+    except BaseException:
+        with open(os.path.join(folder, f"mresults_{proc_id}.err"), 'w') as f:
+            f.write(traceback.format_exc())
+        raise
+
+
+def _worker_impl(proc_id, folder, fields_dir, freq_mode, mode, xrange, procs_epks,
+                 phis, v_init, sey, Epk, step, bounding_rect, loss_model, t_max,
+                 n_points=None):
+    mesh, gfu_E, _ = load_eigenmode_fields(fields_dir)
+    em = build_emfield(gfu_E, mode, freq_mode)
+    # Same wall the parent measured Epk on: densified in-band when n_points asks
+    # for more launch sites than the mesh vertices provide (geometry unchanged).
+    wall, chain = _surface_polyline(mesh)
+    xsurf, chain = densify_wall(wall, xrange, n_points, chain=chain)
+
+    dt = 1 / (freq_mode * 1e6 * 20 * 6)
+    w = 2 * np.pi * freq_mode * 1e6
+    integrator = Integrators(mesh, w, bounding_rect=bounding_rect, loss_model=loss_model)
+
+    n_init_particles = 1
+    particles_objects = []
+    particles_left = []
+    start = time.time()
+    for epk in procs_epks:
+        sub_start = time.time()
+        t = 0.0
+        particles = Particles(xrange, v_init, xsurf, phis, cmap='jet', step=step,
+                              chain=chain)
+        n_init_particles = len(particles.x)
+
+        scale = epk
+        while t < t_max:
+            if particles.len != 0:
+                particles.save_old()
+                integrator.rk4(particles, t, dt, em, scale, sey)
+                particles.update_record()
+            t += dt
+
+        particles_objects.append(particles)
+        particles_left.append(len(particles.bright_set))
+        print(f"\tEpk: {epk * Epk * 1e-6:.2f} MV/m, bright set: "
+              f"{len(particles.bright_set)}, {time.time() - sub_start:.1f}s")
+        # Publish progress (field levels finished by this worker) so the parent
+        # can aggregate a live bar; a small file the parent polls, robust across
+        # the subprocess boundary.
+        try:
+            with open(os.path.join(folder, f"mprogress_{proc_id}"), 'w') as pf:
+                pf.write(str(len(particles_objects)))
+        except OSError:
+            pass
+
+    cn_c0 = np.array(particles_left) / n_init_particles
+    mresult = {'cn/c0': cn_c0, 'particles_objects': particles_objects,
+               'n_init_particles': n_init_particles, 'epks': procs_epks,
+               'phis_v': phis}
+    with open(os.path.join(folder, f"mresults_{proc_id}"), "wb") as file:
+        pickle.dump(mresult, file)
+    print(f"\tProc {proc_id} done ({time.time() - start:.1f}s).")
+
+
+def _read_progress(folder, proc_count):
+    """Total field levels finished so far, summed over the workers' progress
+    files (each holds the count that worker has completed)."""
+    done = 0
+    for p in range(proc_count):
+        try:
+            with open(os.path.join(folder, f"mprogress_{p}")) as f:
+                done += int(f.read() or 0)
+        except (OSError, ValueError):
+            pass
+    return done
+
+
+class _SweepProgress:
+    """Live tqdm bar over the whole sweep, driven by a daemon thread that polls
+    the workers' progress files — so it aggregates across the subprocess workers
+    (and the in-process one) without them writing to the same bar."""
+
+    def __init__(self, folder, proc_count, total, enabled=True):
+        self.folder, self.proc_count, self.total = folder, proc_count, total
+        self.enabled = enabled
+        self._stop = threading.Event()
+        self._thread = None
+        self._bar = None
+
+    def __enter__(self):
+        if self.enabled:
+            self._bar = tqdm(total=self.total, desc='Multipacting sweep',
+                             unit='field')
+            self._thread = threading.Thread(target=self._poll, daemon=True)
+            self._thread.start()
+        return self
+
+    def _poll(self):
+        while not self._stop.is_set():
+            self._bar.n = min(_read_progress(self.folder, self.proc_count), self.total)
+            self._bar.refresh()
+            self._stop.wait(0.3)
+
+    def __exit__(self, *exc):
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=1.0)
+        if self._bar is not None:
+            self._bar.n = self.total
+            self._bar.refresh()
+            self._bar.close()
+
+
+def run_sweep(folder, fields_dir, freqs, sey, *, mode=1, xrange=None, epks=None,
+              phis=None, v_init=2, step=None, proc_count=None, loss_model='field',
+              t_max=1000e-10, progress=True, n_points=None):
+    """Run the peak-field sweep and return the assembled results dict.
+
+    Parameters mirror PyMultipact's ``analyse_multipacting``. *fields_dir* is the
+    eigenmode polarisation folder (``mesh.pkl`` + ``gfu_EH.pkl``); *freqs* is the
+    mode-frequency list [MHz]; *sey* is a :class:`~.sey.SEY`. ``progress`` shows a
+    live tqdm bar over the field levels as the workers finish them.
+    """
+    freq_mode = freqs[mode]
+    lmbda = c0 / (freq_mode * 1e6)
+
+    # peak field + geometry from the eigenmode mesh
+    mesh, gfu_E, _ = load_eigenmode_fields(fields_dir)
+    em = build_emfield(gfu_E, mode, freq_mode)
+    xsurf = _surface_points(mesh)
+    bounding_rect = _bounding_rect(xsurf)
+    Epk = _peak_surface_field(em, mesh, xsurf)
+
+    if epks is None:
+        epks_v = 1 / Epk * 1e6 * np.linspace(0, 80, 192)
+    else:
+        epks_v = 1 / Epk * np.asarray(epks, dtype=float)   # user epks in V/m
+    phi_v = np.linspace(0, 2 * np.pi, 72) if phis is None else np.asarray(phis)
+    if xrange is None:
+        # PyMultipact used a fixed [-0.25, 0] mm band tied to its own z-origin;
+        # cavsim2d's profile has a different origin, so anchor to the geometry.
+        xrange = default_xrange(xsurf)
+    # More launch sites without a finer mesh: interpolate along the wall polyline
+    # inside the band (geometry unchanged). Workers densify identically.
+    xsurf = densify_wall(xsurf, xrange, n_points)
+
+    if proc_count is None:
+        proc_count = max(1, min(mp.cpu_count() - 1, len(epks_v)))
+    proc_count = max(1, int(proc_count))
+    print(f"Multipacting Epk sweep: {len(epks_v)} points on {proc_count} "
+          f"process{'es' if proc_count > 1 else ''}.")
+    sweep_start = time.time()
+
+    # round-robin split, remembering original indices for re-assembly
+    divided, divided_idx = [[] for _ in range(proc_count)], [[] for _ in range(proc_count)]
+    for idx, value in enumerate(epks_v):
+        divided[idx % proc_count].append(value)
+        divided_idx[idx % proc_count].append(idx)
+    proc_epks = [np.array(lst) for lst in divided]
+
+    for p in range(proc_count):                    # clear stale worker outputs
+        for stale in (os.path.join(folder, f"mresults_{p}"),
+                      os.path.join(folder, f"mresults_{p}.err"),
+                      os.path.join(folder, f"mworker_{p}.log"),
+                      os.path.join(folder, f"mprogress_{p}")):
+            if os.path.exists(stale):
+                try:
+                    os.remove(stale)
+                except OSError:
+                    pass
+
+    args = lambda p: (p, folder, fields_dir, freq_mode, mode, xrange, proc_epks[p],
+                      phi_v, v_init, sey, Epk, step, bounding_rect, loss_model, t_max,
+                      n_points)
+    with _SweepProgress(folder, proc_count, len(epks_v), enabled=progress):
+        if proc_count == 1:
+            _worker(*args(0))
+        else:
+            # Workers are plain subprocesses (NOT multiprocessing.Process): mp's
+            # Windows spawn bootstrap re-executes the parent's __main__ in every
+            # child, which requires an `if __name__ == '__main__':` guard in
+            # scripts and breaks outright in notebooks/IPython. A fresh interpreter
+            # running `-m ...driver <argsfile>` imports only this module, so the
+            # sweep works the same from a notebook, an unguarded script, or a test.
+            # Worker stdout/stderr goes to mworker_{p}.log (a child's console is
+            # invisible in notebooks); failures also land in mresults_{p}.err.
+            env = dict(os.environ)
+            pkg_root = str(Path(__file__).resolve().parents[3])  # dir with cavsim2d/
+            env['PYTHONPATH'] = pkg_root + os.pathsep + env.get('PYTHONPATH', '')
+            procs = []
+            for p in range(proc_count):
+                args_path = os.path.join(folder, f"mworker_{p}.args")
+                with open(args_path, 'wb') as f:
+                    pickle.dump(args(p), f)
+                log = open(os.path.join(folder, f"mworker_{p}.log"), 'w')
+                proc = subprocess.Popen(
+                    [sys.executable, '-m', 'cavsim2d.analysis.multipacting.driver',
+                     args_path],
+                    stdout=log, stderr=subprocess.STDOUT, env=env)
+                procs.append((proc, log, args_path))
+            for proc, log, args_path in procs:
+                proc.wait()
+                log.close()
+                try:
+                    os.remove(args_path)
+                except OSError:
+                    pass
+
+    # re-assemble in epks_v order
+    cf_by_idx, po_by_idx = {}, {}
+    n_init = 1
+    for p in range(proc_count):
+        rf = os.path.join(folder, f"mresults_{p}")
+        if not os.path.exists(rf):
+            detail = ''
+            for extra in (f"{rf}.err", os.path.join(folder, f"mworker_{p}.log")):
+                if os.path.exists(extra):
+                    with open(extra) as ef:
+                        tail = ef.read()[-3000:]
+                    if tail.strip():
+                        detail += f"\n--- {os.path.basename(extra)} ---\n{tail}"
+            raise RuntimeError(f"Multipacting worker {p} produced no result "
+                               f"({rf}) -- it crashed.{detail}")
+        with open(rf, "rb") as file:
+            m = pickle.load(file)
+        for local_i, global_i in enumerate(divided_idx[p]):
+            cf_by_idx[global_i] = m['cn/c0'][local_i]
+            po_by_idx[global_i] = m['particles_objects'][local_i]
+        if p == 0:
+            n_init = m['n_init_particles']
+
+    cn_c0 = np.array([cf_by_idx[i] for i in range(len(epks_v))])
+    particles_objects = [po_by_idx[i] for i in range(len(epks_v))]
+
+    for po in particles_objects:
+        distance_function(po, lmbda)
+
+    elapsed = time.time() - sweep_start
+    result = {'cn/c0': cn_c0, 'particles_objects': particles_objects,
+              'n_init_particles': n_init, 'Epk': Epk, 'epks': epks_v,
+              'phis_v': phi_v, 'freq [MHz]': freq_mode, 'mode': mode,
+              'fields_dir': str(fields_dir), 'sweep_time [s]': elapsed}
+    with open(os.path.join(folder, "mresults.pkl"), "wb") as file:
+        pickle.dump(result, file)
+    # Consistent per-analysis timing log (see cavsim2d.utils.run_log).
+    timer = RunTimer(folder, 'multipacting', name=f'mode {mode}',
+                     config={'freq [MHz]': freq_mode, 'mode': mode,
+                             'field_levels': len(epks_v), 'processes': proc_count})
+    timer._t0 = sweep_start
+    timer.add('sweep', elapsed)
+    timer.write()
+    print(f"Multipacting sweep done: {len(epks_v)} field levels, "
+          f"{n_init} launch sites x phases, {elapsed:.1f}s "
+          f"({elapsed / max(len(epks_v), 1):.2f}s per field level).")
+    return result
+
+
+def _worker_main(args_path):
+    """Subprocess entry point: load the pickled worker arguments and run."""
+    with open(args_path, 'rb') as f:
+        worker_args = pickle.load(f)
+    _worker(*worker_args)
+
+
+if __name__ == '__main__':
+    # Invoked by run_sweep as `python -m cavsim2d.analysis.multipacting.driver
+    # <argsfile>` — one sweep worker per interpreter (see run_sweep for why
+    # this is a subprocess, not a multiprocessing.Process).
+    _worker_main(sys.argv[1])

cavsim2d/analysis/multipacting/fields.py

@@ -0,0 +1,134 @@
+"""Field adapter: cavsim2d eigenmode result -> multipacting EM field.
+
+The particle integrator evaluates ``em.e(mesh_points)`` (in-plane E, a 2-vector
+(E_z, E_r)) and ``em.h(mesh_points)`` (azimuthal H, scalar) directly on the
+GridFunctions. cavsim2d's eigenmode field is a **product space** ``(u, u_phi)``,
+so this adapter:
+
+- takes E from the in-plane HCurl block, ``gfu_E[mode].components[0]``;
+- **reconstructs** H as ``1j/(mu0*w) * curl(E_inplane)``.
+
+The reconstruction is deliberate. cavsim2d stores a magnitude-only ``H_phi``
+(the ``1j`` dropped, since only |H| enters the QOIs), but multipacting integrates
+E and B together over the RF cycle and needs the physical 90-degree E-H phase
+that the ``1j`` carries. Rebuilding H from ``curl(E)`` reproduces the field
+PyMultipact used exactly.
+"""
+import json
+import os
+
+import numpy as np
+from ngsolve import curl
+
+from cavsim2d.constants import mu0
+from cavsim2d.solvers.NGSolve.eigen_ngsolve import NGSolveMEVP, mesh_h_metres
+from cavsim2d.solvers.eigenmode_result import pol_number
+
+
+
+class EMField:
+    """Holder whose ``.e`` / ``.h`` are coefficient functions the integrator
+    evaluates directly at mesh points (``em.e(mesh(z, r))``)."""
+
+    def __init__(self, e, h):
+        self.e = e
+        self.h = h
+
+
+def build_emfield(gfu_E, mode, freq_mhz):
+    """In-plane E and reconstructed azimuthal H for a monopole product-space mode.
+
+    Parameters
+    ----------
+    gfu_E : list
+        The eigenmode E fields (product-space GridFunctions) from ``gfu_EH.pkl``.
+    mode : int
+        Mode index.
+    freq_mhz : float
+        Mode frequency [MHz], for the reconstruction weight ``w = 2*pi*f``.
+    """
+    w = 2 * np.pi * freq_mhz * 1e6
+    e_inplane = gfu_E[mode].components[0]         # HCurl block: (E_z, E_r)
+    h_phi = 1j / (mu0 * w) * curl(e_inplane)      # physical azimuthal H
+    return EMField(e_inplane, h_phi)
+
+
+def load_eigenmode_fields(fields_dir):
+    """Load ``(mesh, gfu_E, gfu_H)`` from an eigenmode polarisation folder.
+
+    Delegates to :meth:`NGSolveMEVP.load_fields`, which rebuilds the product
+    space on the saved (round-tripping ``.vol``) mesh and reloads the projected
+    coefficient vectors — so this works uniformly for fixed and **adaptively
+    refined** solves (a raw ``gfu_EH.pkl`` pickle does not round-trip a refined
+    mesh). Kept separate from :func:`build_emfield` so a worker process can load
+    once and build the field per swept mode. The mesh returned is the field's own
+    (curved to the solve order), so field evaluations land on the render mesh.
+    """
+    solver = NGSolveMEVP()
+    gfu_E, gfu_H = solver.load_fields(fields_dir, 0)
+    mesh = gfu_E[0].space.mesh if gfu_E else solver.load_mesh(fields_dir)
+    return mesh, gfu_E, gfu_H
+
+
+def solve_multipacting_field(cav, save_dir, mesh_config=None, n_modes=None,
+                             polarisation='monopole'):
+    """Solve the eigenmode on a multipacting-specific mesh, into the
+    multipacting analysis' OWN field folder.
+
+    Used when a custom surface refinement (``pec_maxh``) is requested: the
+    surviving electrons live in a sub-millimetre layer at the wall, so
+    multipacting needs a finer PEC surface than the eigenmode QOIs do. Solving
+    on a separate mesh here leaves ``cav.eigenmode``'s results (and everything
+    downstream of them) completely untouched — each analysis stays internally
+    consistent with its own mesh.
+
+    *mesh_config* takes ``h`` / ``p`` (global size [mm] / order, as in the
+    eigenmode config) plus ``pec_maxh`` (local PEC surface size [mm]).
+    *polarisation* selects the azimuthal order to solve ('monopole', 'dipole', ...)
+    and *n_modes* how many modes of it — so multipacting can be driven by, say, the
+    second monopole mode or a dipole mode. Writes
+    ``mesh.pkl`` + ``gfu_EH.pkl`` + ``freqs.json`` into *save_dir* (the same
+    layout as an eigenmode polarisation folder, so the sweep driver reads it
+    unchanged) and returns the mode-frequency list [MHz].
+    """
+    cfg = dict(mesh_config or {})
+    maxh = mesh_h_metres(cfg, default=6)
+    order = cfg.get('p', 3)
+    pec_maxh = cfg.get('pec_maxh')
+    edge_maxh = {'PEC': float(pec_maxh) * 1e-3} if pec_maxh else None
+
+    maker = getattr(cav, 'profile', None)
+    profile = maker() if callable(maker) else None
+    if profile is None:
+        raise RuntimeError(
+            f"{type(cav).__name__} {cav.name!r} has no profile(), so a "
+            f"multipacting-specific (PEC-refined) mesh cannot be built. Run "
+            f"without pec_maxh to reuse the eigenmode field instead.")
+
+    solver = NGSolveMEVP()
+    n = solver.requested_n_modes(cav, None, n_modes)
+    # The mesh is deliberately STRAIGHT (order=1 geometry, no Curve): the
+    # tracker's collision surface is the polyline through the wall vertices,
+    # and on a curved mesh that polyline disagrees with the element boundary by
+    # the chord sagitta — impact points computed on the polyline then fall
+    # OUTSIDE the curved mesh and the field evaluation throws ("Meshpoint not
+    # in mesh"), first at concave wall sections. A straight mesh makes the
+    # collision polyline coincide with the element edges exactly — the same
+    # construction PyMultipact validated (polygon boundary + order-3 fields).
+    # With the fine pec_maxh wall the geometric error is the chord sagitta
+    # (~h^2/8R, micrometres); the field itself keeps the full order *p*.
+    mesh = profile.mesh(maxh=maxh, order=1, edge_maxh=edge_maxh)
+    system = solver._build_system(mesh, order, pol_number(polarisation))
+    freqs, gfu_E, gfu_H = solver._solve_system(system, n)
+
+    os.makedirs(save_dir, exist_ok=True)
+    solver.save_mesh(save_dir, mesh)
+    # geom_order=1: the own-field mesh is STRAIGHT (built with order=1 above) and
+    # must stay straight on reload so the tracker's collision polyline coincides
+    # with the element edges — see the mesh comment above.
+    solver.save_fields(save_dir, gfu_E, gfu_H, order, pol_number(polarisation),
+                       freqs, geom_order=1)
+    freqs = [float(f) for f in freqs]
+    with open(os.path.join(save_dir, 'freqs.json'), 'w') as f:
+        json.dump(freqs, f, indent=4)
+    return freqs