Tabulated wakefields and IMPACT-Z interchange

[ChristopherMayes]

Tabulated wakefields and IMPACT-Z interchange

Summary

This branch makes TabularWakefield the interchange format between the analytic wakefield models and external tracking codes, and adds IMPACT-Z support on top of it.

• TabularWakefield.from_wakefield resamples any WakefieldBase onto a uniform grid.
• ResistiveWallWakefieldBase.to_tabular tabulates either resistive wall model over a default range of 100 * s0.
• create_impact_z_wakefield_rfdata returns the uniform four-column table consumed by the IMPACT-Z zero-length -41 element, and write_impact_z_wakefield writes it.
• parse_impact_z_wakefield and TabularWakefield.from_impact_z read such a table back into the z <= 0 convention, from either a path or an array.

Impact

A resistive wall model can now be handed to IMPACT-Z without hand-written glue code, and a table produced elsewhere can be read back for comparison against the analytic models.
The round trip through the writer and reader is exact, and a re-imported table agrees with its parent model to 2.6e-08 of W0 for a copper pipe of 2.5 mm radius.

Both entry points work on arrays as well as paths, because a driver such as lume-impact holds its input as dict[str, NDArray] and decides where the file belongs only at run time.
The sign convention, the mirror from z to s and the 5000-row limit of Ndataini therefore live in one place rather than being reimplemented downstream.

Notes on three decisions

The default tabulation range is 100 * s0 rather than a smaller multiple, because the pseudomode decay length is governed by k_r / 2 Q_r rather than by s0 and still holds up to 24 % of W0 at 20 * s0.

from_wakefield enlarges the transform length when it resamples an ImpedanceWakefield.
The default grid reaches only about 2.6 mm, so a 10 mm aluminium pipe wrapped around and returned 0.70 of W0 in the tail.
This is a pre-existing limitation of ImpedanceWakefield.wake, which is otherwise unchanged.

The writer emits 17 significant digits.
At 12 digits the rounded first abscissa fell outside the range of the re-read table, and the interpolant returned its fill value there.

The same fill value motivates a guard in from_wakefield.
Resampling a TabularWakefield over a range wider than the source covers used to produce a silently zero-padded table, and now raises, naming both the requested range and the range available.

Testing

tests/test_wakefields.py adds 27 tests, including a round trip through the IMPACT-Z writer and reader and a check that the written file agrees with the array the builder returns.
The fixture tests/data/rfdata41.in holds the first 200 rows of the IMPACT-Z examples/Example3 table, unmodified, so that the parser is exercised against Fortran-formatted columns that this package did not write.
The full suite passes, ruff reports no new findings, and both wakefield notebooks execute.

Acknowledgement

This work was carried out with Claude Opus 5 running as GitHub Copilot in Visual Studio Code.
The model wrote the implementation, the tests and the documentation, and ran every measurement quoted above on the local machine against the working tree.
The author reviewed the change before submitting it.