Add resistive wall Wakefields

[ChristopherMayes]

Based on my work on this branch, here's a summary for the PR:

---

PR: Add Resistive Wall Impedance Module

Summary

This PR adds a new ResistiveWallImpedance class for computing longitudinal resistive wall impedance Z(k) and wakefield W(z) via direct numerical integration. This complements the existing ResistiveWallWakefield pseudomode approach by providing high-accuracy calculations suitable for validation and research.

New Features

ResistiveWallImpedance class

• Supports both flat (parallel plate) and round (circular pipe) geometries via a geometry parameter
• Computes impedance Z(k) using surface impedance formalism with AC conductivity (Drude model)
• Computes wakefield W(z) via cosine Fourier transform of Re[Z(k)]
• Built-in plot_impedance() and plot_wakefield() convenience methods
• Backwards-compatible factory functions FlatResistiveWallImpedance() and RoundResistiveWallImpedance()

Physics formulas implemented

• Flat geometry (SLAC-PUB-10707 Eq. 52):
  $$Z_\parallel(k) = \frac{Z_0}{2\pi a} \int_0^\infty \frac{dx}{\cosh(x)[\cosh(x)/\zeta - ika \cdot \text{sinhc}(x)]}$$

• Round geometry (SLAC-PUB-10707 Eq. 2, PhysRevSTAB.18.034402 Eq. 7):
  $$Z_\parallel(k) = \frac{Z_0}{2\pi a}\left(\frac{1}{\zeta(k)} - \frac{ika}{2}\right)^{-1}$$

• Wakefield (Chao Eq. 2.24):
  $$W(z) = \frac{2c}{\pi} \int_0^{k_{\max}} \text{Re}[Z(k)] \cos(kz) , dk$$

Low-level functions exposed

• ac_conductivity() — Drude model AC conductivity
• surface_impedance() — Surface impedance for conducting wall
• longitudinal_impedance_flat() / longitudinal_impedance_round() — Direct impedance calculation
• wakefield_from_impedance() — Wakefield via Fourier transform
• characteristic_length() — Characteristic length scale s₀

Improvements to existing ResistiveWallWakefield

• Lazy matplotlib import — No longer a hard dependency at import time
• Added __repr__ — Shows all parameters plus derived values (s₀, Γ, k_r, Q_r)
• Fixed typo — "conductivtity" → "conductivity"
• Standardized docstrings — Full NumPy-style docstrings for helper functions
• Harmonized validation — relaxation_time >= 0 now consistent across modules

Documentation

• New example notebook: resistive_wall_impedance.ipynb
  • Demonstrates flat and round geometries
  • Compares numerical integration with pseudomode approximation
  • Shows performance comparison (~1000x speedup for pseudomode)
• Improved existing notebook: resistive_wall_wakefield.ipynb
• Added to mkdocs navigation

References

• K. Bane and G. Stupakov, SLAC-PUB-10707 (2004)
• G. Stupakov et al., Phys. Rev. ST Accel. Beams 18, 034402 (2015)
• A. Chao, "Physics of Collective Beam Instabilities," Wiley (1993)

---

[Copilot]

Pull request overview

This PR adds a comprehensive resistive wall impedance module (ResistiveWallImpedance) that computes longitudinal impedance Z(k) and wakefield W(z) through direct numerical integration. This complements the existing fast pseudomode approximation (ResistiveWallWakefield) by providing high-accuracy calculations suitable for validation and research applications.

Key changes:

• New ResistiveWallImpedance class supporting flat and round geometries with direct impedance/wakefield calculations
• Enhanced ResistiveWallWakefield with lazy matplotlib imports, improved __repr__, and standardized validation
• Added wakefield_plot() visualization function to ParticleGroup and plot module
• Updated documentation with two example notebooks and navigation entries

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pmd_beamphysics/wakefields/resistive_wall_impedance.py	New module implementing numerical impedance/wakefield calculations with AC conductivity support
pmd_beamphysics/wakefields/resistive_wall.py	Existing pseudomode wakefield implementation with improved documentation and lazy imports
pmd_beamphysics/wakefields/init.py	Module initialization exporting both wakefield classes and utility functions
pmd_beamphysics/plot.py	Added wakefield_plot() function and enhanced density_plot() with flexible axis support
pmd_beamphysics/particles.py	Added wakefield_plot() method to ParticleGroup class
mkdocs.yml	Added wakefields section to documentation navigation
docs/examples/wakefields/resistive_wall_wakefield.ipynb	Tutorial notebook for pseudomode wakefield usage
docs/examples/wakefields/resistive_wall_impedance.ipynb	Tutorial notebook comparing numerical and pseudomode approaches
docs/examples/data/SLAC-PUB-10707-digitized-Fig8-AC-Cu.csv	Reference data for flat geometry validation
docs/examples/data/SLAC-PUB-10707-digitized-Fig4-AC-Cu.csv	Reference data for round geometry validation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.