WakeField

WakeField computes wake-induced energy and transverse momentum changes from a named longitudinal slice set. Each command represents one physical interaction point, with independent source history or modal state for each algorithm group. It supports analytic responses, temporal tables, and impedance spectra, using the same configuration on CPU and NVIDIA GPU.

Execute a matching Longitudinal slicing (Slicer) before the interaction point. Ordinary causal responses use continuous arrival times; conditions for periodic coasting-beam slices are given below. Response data must specify units, signs, normalization, and a velocity model. Regenerate slices after regrouping; emitted history retains its original physical times and widths. See Longitudinal coordinate and reference time for coordinates.

Several wake commands may reference the same named SliceSet while retaining independent wake histories. That set cannot also serve another physical module, such as BeamBeam. Input validation checks sharing and the Slicer’s Purpose together: wakes require general slices, even if no BeamBeam command reads the selected set. WakeField accepts only z_rel or arrival_phase slicing; collision_z is not a laboratory arrival-time coordinate, even after the particles have returned from the collision frame.

Shared configuration and wake points

The optional root-level Wake field block contains Enabled (default true) and Configurations, a mapping from unique names to objects containing Groups. A wake point supplies either its inline Groups or a Configuration reference, exclusively. S (m), Slice set and Is enabled remain per-point parameters. Both enable switches must be true for a point to execute. Without a root block, define Groups directly in each command.

Configurations share input parameters only. Loading the input expands each reference into an independent definition; each physical point constructs its own models, histories and solver state. Disabling the module does not permit invalid configurations or missing references. File paths in shared definitions are resolved relative to the input JSON, as for inline definitions.

For example, a root block and a corresponding entry inside Sequence are:

"Wake field": {
    "Enabled": true,
    "Configurations": {
        "pipe": {"Groups": [{
            "Name": "longitudinal", "Solver": "direct", "History": "none",
            "Components": [{
                "Component": "longitudinal", "Velocity": {"Kind": "ideal"},
                "Model": {"Kind": "constant", "Amplitude": 1e12, "Duration (s)": 1e-6}
            }]
        }]}
    }
},
"Sequence": {
    "wake_1": {"Command": "WakeField", "S (m)": 1.0,
               "Slice set": "wake", "Configuration": "pipe", "Is enabled": true}
}

This is an interface fragment: supply Injection, optics and the matching Slicer before the wake point. The constant model is illustrative, not a prescribed machine impedance. The Python API exports WakeFieldConfig and WakeResourceConfig; pass wake_field=WakeFieldConfig(...) to generate_input.

Explicit algorithm groups

Command fields are S (m), Command="WakeField", Slice set, Groups or Configuration, and Is enabled. Groups have unique Name values and nonempty Components lists. Each component selects Component, Model, Velocity, optional Scale and Field content.

Group execution controls
Field	Meaning
`Solver`	Required: `direct`, `fft`, `quasistatic_fft` (current-velocity full-ring history), `recursive` (resonator), `modal` (pole/residue), `partitioned_fft` (stationary gapped train), or `time_fft` (variable-period physical-time history).
`History`	Required: `none`, `direct` (stored source bins), `state` (resonator/modal state), or `partitioned`. `quasistatic_fft` requires `direct`; the last requires `partitioned_fft` or `time_fft`.
`Source shape`	`uniform` (default) or `point`; independently selected per group.
`Memory turns`	Positive integer or null for direct history; required finite positive integer for `quasistatic_fft` and `partitioned_fft`. Counts preceding passages, with the current passage also included. Must be null for `time_fft`.
`Memory time (s)`	Positive value or null for direct/partitioned history; required finite positive value for `time_fft` and must be null for `quasistatic_fft`. Clips the kernel at this delay, including a partial uniform source bin. Physical-time projection introduces mesh error at a discontinuous cutoff.
`Convolution grid`	Required for `partitioned_fft`; stationary physical time layout described below.
`Time grid`	Required only for `time_fft`: positive finite `Step (s)`, integer `Block size` >= 2 (default 64), and optional finite `Origin (s)` (default null).
`Partition`	`dyadic` (default for partitioned FFT) or `uniform`. No automatic algorithm switch.
`Max workspace (MiB)`	Partitioned FFT conservative peak allocation budget, default 1024 MiB. Checked before allocating history; CUDA also checks available device memory.
`Boundary`	`causal_passages` (default), `isolated`, or `periodic`.
`Period (s)`, `Periodic images`	Both required for periodic response; use direct solver and no transient history. Images -N through +N are summed explicitly.

fft requires an increasing uniform current grid with equal source widths no larger than the spacing. With History="direct", previous passages are explicitly calculated directly using saved physical times and widths. This existing fft behavior is unchanged. quasistatic_fft instead evaluates the retained history by FFT using the explicit approximation described below; its History="direct" denotes snapshot storage, not direct summation. No auto option or silent solver fallback is provided. Modes retain unlimited decay history with memory proportional to mode count. Gaps between bunches use physical elapsed time.

Physical-time causal solvers require passages to be ordered and nonoverlapping in physical time, including uniform-bin support. Overlap across tracking turns is rejected: turn-batched tracking cannot infer future trajectories. A spatial isolated boundary declares that the complete source train is present in the current batch; periodic declares its repeated steady state. Both require fixed beta and no transient history. They cannot be used to represent arbitrary accelerating or transient ring distributions. The user chooses the number of periodic images and checks convergence.

Response models

Models (`Kind` in each component’s `Model`)
Kind	Parameters and interpretation
`constant`	`Amplitude`, `Duration (s)`. Finite causal test response.
`resonator`	Positive `R`, `Q`, `Frequency (Hz)`. R is the real impedance at resonance; amplitude decay rate is $\pi f_r/Q$. Under-, critical- and over-damped cases are supported.
`tabulated`	Increasing `Times (s)`, matching `Values`, `Causal` (default true). Linear interpolation, zero outside the table. Causal tables start at zero; two-sided tables can include negative delays.
`file`	Canonical wake TFS only. Convert external CSV/TXT/HEADTAIL data before tracking. See File input below. Loaded once, with content fingerprinting.
`impedance`	Increasing nonnegative `Frequencies (Hz)`, matching `Real`/`Imag`, explicit `Reconstruction`. Original samples remain immutable.
`fitted_impedance`	The same spectrum plus `Initial poles (1/s)` as [real, imaginary] pairs, `Optimize poles`, `Max evaluations`, `Relative floor`, `Fit tolerance`. Supply only the positive-imaginary pole of each conjugate pair, or real poles.
`modes`	`Poles (1/s)` and `Residues` as [real, imaginary] pairs, with both members of every conjugate pair explicitly present. Real poles require real residues.
`resistive_wall`	Finite-beta round good-conductor thick wall: `Radius (m)`, `Conductivity (S/m)`, `Length (m)`, `Beta`, `Frequencies (Hz)`. Optional `Wall thickness (m)` checks the thick-wall condition; it does not activate a finite-wall field-matching solver.
`ultrarelativistic_wall`	Bane-Sands round DC wall, `Radius (m)`, `Conductivity (S/m)`, `Length (m)`. Requires beta >= 0.99; additional short-bunch validity must also be assessed.

The finite-beta wall implements Stupakov, PRAB 23, 094401 (2020), doi:10.1103/PhysRevAccelBeams.23.094401. It supports longitudinal and diagonal dipolar components. It subtracts the perfect-conductor response for the identical round geometry and supplies only the finite-conductivity correction. Scaled Bessel functions retain the finite beta dependence and avoid overflow. DC is outside this model’s validity. Max skin depth ratio bounds skin depth divided by radius, and also thickness when supplied. Max surface impedance ratio bounds the normalized surface impedance. Both default to 0.1 and cannot exceed 0.1. Finite wall thickness, magnetic/dispersive materials and arbitrary geometry require an appropriate validated response; this model does not infer them.

Field content declares wake, finite_conductivity_correction, pec_image, direct_space_charge or total. PASS does not automatically subtract space charge. Existing SpaceCharge calculations are transverse and do not establish that longitudinal or all image terms are present. Combine terms only after checking geometry, normalization and physical content.

Example

from PASS.para.schema import WakeField

wake = WakeField(s=0, slice_set="wake", groups=[
    dict(name="short", solver="fft", history="none", source_shape="uniform",
         components=[dict(component="longitudinal", velocity=dict(kind="ideal"),
             model=dict(kind="resonator", r=1e3, q=1, frequency=1e8))]),
    dict(name="long", solver="recursive", history="state", source_shape="point",
         components=[dict(component="dipolar_y",
             velocity=dict(kind="factorized", betas=[0.01, 0.5, 1.0],
                           source=[0.2, 1.0, 0.8], witness=[0.1, 0.3, 1.0]),
             model=dict(kind="resonator", r=1e6, q=1e6, frequency=1e7))]),
])

The coupling numbers in this example are illustrative, not cavity field data. Configure and execute a named Slicer before WakeField. Components/Solver/Memory turns interface must migrate to Groups; there is no compatibility interpretation of obsolete fields.

Diagnostics and state

The command exposes last_sources, last_coefficients, last_diagnostics and group_states. Diagnostics include each selected algorithm, boundary, retained passage count, state bytes and fit errors. state_dict() and load_state_dict() serialize/restore all groups and check a configuration fingerprint. These methods cover wake state only. reset_state() starts the location with zero field.

For recursive/modal history, a checkpoint that has processed a nonempty source must contain the state of every component, its turn, and both history clocks. Missing or repeated components are rejected instead of resetting part of the field to zero. A fresh state, or a state that has processed only empty passages, may have no modes. The two clocks are not required to be numerically identical: conversion from a local GPU time origin can round their representations differently. Restored modal arrays use complex128; recursive resonator arrays use float64 and cannot contain a nonzero imaginary part. Failed validation leaves the current command state intact.

Executor.run(sim, sequences) always starts at turn 0. Enabled WakeField commands must have no retained history at the start of a new run; call reset_state() before reusing a WakeField command for a newly initialized simulation.

All macro particles in a beam share one fixed weight from the initial injection inputs. Source projection uses bunch.ratio * bunch.num_charge * e as the charge per live macro particle on CPU and GPU, without an individual-charge array. The Executor does not copy tags or update source charges around Injection commands; newly activated particles retain their original weights. See Injection / Particle Generation.

File input

Model.Kind="file" reads canonical wake TFS only. Its model fields are Kind="file", required File path, Format="tfs" (default), and Reconstruction (default two_sided, used for impedance spectra). Units, signs, spatial powers and temporal causality come from the file. Component and Velocity remain explicit component-level settings.

CSV, whitespace tables and HEADTAIL files must first be converted with PASS.tool.wake_conversion or the GUI wake importer. Tracking no longer accepts Format="table" or "headtail", nor the former model fields Convention, Axis column, Value column, Imag column, Delimiter, Skip rows, Causal or Length (m). These source interpretation settings belong to the conversion step. Renaming an external file to .tfs is insufficient: it must contain the canonical columns and required headers below.

Temporal tables use linear interpolation and zero response outside their support. Causal tables start at zero delay. The converter rejects duplicate or unordered samples and can reorder a reversed time/distance axis; it retains the original sample locations after unit and direction conversion.

Input JSON resolves File path relative to its directory. Direct Python construction uses the supplied path relative to the current directory. Files are read only at construction; source hash and conversion metadata remain on the model. Checkpoints verify file-content hashes as well as configuration. CST project/binary parsing, automatic unit detection and wake-potential deconvolution are not included. Export numeric data and convert it using its explicitly declared source conventions.

Canonical wake TFS and external conversion

Use one TFS file per wake component. The canonical time-domain columns are TAU and W: delay in seconds and the integrated point-charge wake in SI units. Positive delay means a trailing witness; positive longitudinal wake means energy loss. The amplitude unit is V/C/m^n, where n is the sum of the source and witness transverse powers (V/C for the longitudinal monopole). Impedance files use FREQUENCY, REAL and IMAG in Hz and the corresponding integrated SI impedance units.

Header names and canonical values are case-sensitive. All headers below are required except SOURCE_METADATA; CAUSAL and ZERO_VALUE are required only for temporal wakes and forbidden for impedance spectra. Header records use @ NAME TYPE VALUE before the * column names and $ column types. All data columns have real floating types (the writer uses %le), and all numeric samples and metadata must be finite.

Canonical wake TFS version 1 headers
Header	Type	Value
`PASS_WAKE_VERSION`	`%d`	`1`.
`DATA_KIND`	`%s`	`wake_function` or `impedance`.
`COMPONENT`, `PLANE`	`%s`	Configured component name and its plane (`x`, `y` or `z`); both must match the selected component.
`SOURCE_POWERS`, `TEST_POWERS`	`%s`	JSON lists `[x_power, y_power]` matching the component; for example, `"[0, 0]"` for each longitudinal monopole factor.
`AXIS_UNIT`	`%s`	`s` for temporal wakes; `Hz` for impedance spectra.
`VALUE_UNIT`	`%s`	`V/C` for wakes or `ohm` for impedance at order zero; append `/m` at order one or `/m^n` at higher order n.
`REFERENCE_BETA`	`%le`	Reference speed divided by c, with `0 < beta <= 1`.
`INTEGRATED`, `POSITIVE_TRAILING`, `LONGITUDINAL_POSITIVE_LOSS`	`%d`	Each is `1`: integrated response, positive-trailing delay and positive longitudinal loss.
`FOURIER_EXPONENT`	`%d`	`-1`.
`TRANSVERSE_IMPEDANCE_FACTOR`	`%s`	`i`.
`SHUNT_IMPEDANCE_CONVENTION`	`%s`	`not_applicable`; samples are already normalized. Original source conventions may be retained in provenance.
`CAUSAL`, `ZERO_VALUE`	`%d`, `%s`	Temporal wakes only: `1` and `right_limit` for causal tables, or `0` and `sample` for two-sided tables.
`SOURCE_METADATA`	`%s`	Optional quoted JSON object containing source provenance, such as its hash and original import convention.

The TFS headers record the component, source/witness powers, data kind, units, signs, normalization, reference beta and causal convention. A causal time-domain zero-delay sample stores the right limit $W(0^+)$; the solver applies the half-self-interaction rule. Supply the full right limit, without halving it in the file. A nonzero final wake sample warns of truncation because the response is zero beyond the supplied support. Extend the source data and check convergence when this truncation matters.

Convert exported CSV, whitespace tables or HEADTAIL data with the dedicated PASS.tool.wake_conversion utility. It checks the declared physical conventions, converts units and signs, and writes canonical TFS. It preserves the original sample locations after unit/direction conversion: it does not resample the response or convert delay to tracking turns. The general CSV/TFS converter only changes table representation; it does not establish this wake-specific physical contract.

The converter’s format is table by default; use headtail for its specific unit contract. Numeric columns are zero-based and distinct: axis_column=0 and value_column=1 are defaults, with imag_column required for impedance. delimiter=None selects whitespace, and skiprows=0 skips no initial rows. UTF-8 files support # comments and a byte-order mark. Specify causal=False for a two-sided temporal response.

The convention dictionary declares data_kind (wake_function or impedance), axis (time, distance or frequency), axis_unit, value_unit, positive_trailing, longitudinal_positive_loss, integrated and reference_beta. fourier_exponent defaults to -1, transverse_impedance_factor to i (also -i or 1), and shunt_impedance_convention to not_applicable. The last field records provenance without rescaling already normalized samples.

Time units are s/ms/us/ns/ps, distance units m/cm/mm, and frequency units Hz/kHz/MHz/GHz. Wake amplitudes use V/kV/MV divided by C/nC/pC and the required spatial powers, such as V/C/m^2 or V/(pC*mm). Impedance units use ohm/Ohm/kOhm/MOhm and spatial powers. Per-length data add one denominator length power and require length in metres; integrated data forbid it. Impedance requires real and imaginary columns and positive-trailing delay; declare the Fourier exponent to convert an opposite transform sign. Finite-band causal projection retains its documented approximation.

For a distance axis, distinguish the source’s definitions explicitly in convention: distance_convention="beta_c_tau" (default) means $s=\beta_{\mathrm{ref}}c\tau$, while "c_tau" means $s=c\tau$. Select the latter with --distance-convention c_tau. The conversion changes the delay axis without an additional wake-amplitude Jacobian. These definitions coincide only at beta = 1; the tool does not infer one from a column labelled distance or z.

HEADTAIL supports multiple column layouts, so select the columns explicitly. Its contract is ns and integrated V/pC at order zero, V/(pC*mm) at order one; signs remain explicit. See the CERN HEADTAIL table specification. The output SOURCE_METADATA preserves the source hash and complete import settings, including column mapping, skipped rows, delimiter, length, causality, reconstruction and distance definition, for reproducibility.

For example, save this illustrative nonuniform table as wake.csv:

# delay_ns,wake_V_per_pC
0,4
0.25,3
0.8,1
2,0

Convert it with:

python -m PASS.tool.wake_conversion wake.csv wake_longitudinal.tfs --component longitudinal --axis time --axis-unit ns --value-unit V/pC --reference-beta 0.9 --delimiter ","

The defaults declare positive-trailing delay, positive longitudinal loss and an integrated response. Use --negative-trailing or --positive-gain only when that is the source’s convention. Per-length data require --per-length --length LENGTH_IN_METRES and the corresponding per-length amplitude unit. Select columns and skipped header rows explicitly when the source has a different layout. A finite-bunch wake potential requires separate deconvolution and is rejected as a point-charge wake.

Place the resulting component in a group’s Components list:

{
    "Component": "longitudinal",
    "Velocity": {"Kind": "fixed", "Beta": 0.9},
    "Model": {
        "Kind": "file",
        "Format": "tfs",
        "File path": "wake_longitudinal.tfs"
    }
}

Keep Velocity explicit and consistent with the file’s reference beta. The example describes a stationary response at beta = 0.9; changing the tracking speed does not derive a new response from that table. The normal Slicer, group solver and source-history configuration is still required.

The selected Component must match the file. Temporal causality and conventions are read exclusively from the TFS headers. For impedance TFS, choose Reconstruction in the tracking model; the spectrum does not declare temporal causality. The minimal file model above is sufficient for temporal wakes because Format defaults to tfs.

The Qt-independent Python APIs are preview_wake_file(source, **options) and convert_wake_file(source, destination, **options) in PASS.tool.wake_conversion. Its read_external_wake(source, **options) function reads declared table/headtail input into an SI response model; read_wake_file in the runtime package reads canonical TFS only. Import options include component, column selection and a convention dictionary or WakeConvention. Conversion defaults to overwrite=False; expected_sha256 can protect a previewed source against changes before saving. For the CSV example:

from PASS.tool.wake_conversion import convert_wake_file, preview_wake_file

options = dict(
    component="longitudinal", format="table", axis_column=0, value_column=1,
    delimiter=",", convention=dict(
        data_kind="wake_function", axis="time", axis_unit="ns", value_unit="V/pC",
        positive_trailing=True, longitudinal_positive_loss=True, integrated=True,
        reference_beta=0.9, fourier_exponent=-1, transverse_impedance_factor="i",
        shunt_impedance_convention="not_applicable"))
preview = preview_wake_file("wake.csv", **options)
result = convert_wake_file(
    "wake.csv", "wake_longitudinal.tfs", expected_sha256=preview["sha256"], **options)

For read-only inspection of an existing canonical file, use preview_wake_file("wake_longitudinal.tfs", format="tfs"); the component is read from its headers. TFS preview and successful conversion return component_config, a component JSON fragment with explicit fixed velocity and any required spatial or reconstruction settings. Raw-file preview leaves this field null because no canonical output path exists yet.

Large-table preview keeps the endpoints and extrema of bounded sample groups instead of selecting evenly spaced rows, so narrow peaks remain visible. Full-table diagnostics report the peak magnitude, tail-to-peak ratio and sample-spacing range. Preview reduction only affects display; export preserves all original knots.

The GUI exposes the same workflow through Import wake… in Data format conversion.

Coasting beams

A coasting beam can be represented by one bunch group with harmonic_number=1 and an equal-length explicit Slicer covering a full circumference. This permits full-ring charge/current and transverse-moment profiles; it does not require RF bunching. For uniform current I and a finite causal response, the settled voltage is $V=I\int_0^\infty W(\tau)d\tau$. Zero initial history produces a startup transient; allow the response memory to fill. Boundary="periodic" is a prescribed repeated steady distribution, with image-count convergence, rather than evolving transient history.

For evolving coasting profiles, use Coordinate=arrival_phase (or Periodic=true), equal_length and an explicit interval of length C, such as [-C,0] or [-C/2,C/2]. At an explicit Slicer update, $z_{phase}=z_{max}-C[(z_{max}/C-u)\bmod1]$ with $u=v_{obs}(T_{obs}-t_i)/C$. The prescribed clock selects the common observation event and velocity; see Longitudinal slicing (Slicer). Bunch reference times and velocities may differ. All populations must share the saved observation window and circumference, and Slicer must be at the wake location.

The bins cover $[T_{obs}-z_{max}/v_{obs},T_{obs}-z_{min}/v_{obs})$. Slicer obtains both endpoints from consecutive integrated-clock boundaries, so accelerating windows remain contiguous. An exact seam phase maps to the window start and slice 0, rather than its excluded right endpoint. A new physical source passage requires a user Slicer update; reusing a periodic snapshot retains its old window. No automatic reslicing is performed. Use Boundary="causal_passages" for evolving history. Variable, non-overlapping passage windows are supported by time_fft; a fixed convolution grid still requires its documented timing.

This is the one passage per particle per reference turn approximation. It supports long accumulated slip and momentum spread within this model, but does not schedule zero or multiple individual crossings during one turn. For a uniform rigid stream with actual period Ti, the represented current is Q/T instead of Q/Ti. If epsilon=1-Ti/T, the relative current error is abs(epsilon). This first-order error decreases with momentum deviation.

Require small per-turn slip, small collective change within a turn, and $2\pi |m\,\Delta u|\ll1$ for each resolved azimuthal mode m. Converge slice count and the time mesh separately. Max phase slip (default 0.05, at most 0.1) rejects large observed single-step phase changes when WakeField consumes the slices; diagnostic Slicer projections remain available. It is a guard, not a universal accuracy tolerance. Floating particle storage must also resolve the slice width after accumulated motion; prefer float64 for long coasting runs. An ordinary explicit Slicer keeps its original boundary clipping behavior unless periodic arrival slicing is enabled.

Quasistatic full-ring history

Set Solver="quasistatic_fft", History="direct", Boundary="causal_passages" and a finite positive Memory turns=H. Do not set Memory time (s), Convolution grid, Time grid, Partition, Max workspace (MiB) or periodic-boundary parameters. Both Source shape="point" and "uniform" are supported. The GUI selects direct history and defaults an unset H to 10 when this solver is selected.

This solver requires one PASS bunch and an explicit full-circumference, uniform Coordinate="arrival_phase" Slicer at the wake position, executed in the current tracking turn. The one PASS bunch may contain several physical RF bunches. A local bunch interval, multiple PASS bunches, changing slice counts or nonuniform snapshot grids are rejected. Nonempty grids require at least two slices. Empty bins are allowed and remain part of the full-ring grid.

At each evaluation let N be the number of bins and let the current bunch reference velocity define

\[T_n = \frac{C}{\beta_n c}, \qquad \Delta t_n = \frac{T_n}{N}, \qquad \tau^{\rm qs}_{n,i;m,j} = [(n-m)N+i-j]\Delta t_n .\]

Here i and j increase in arrival-time order and m is a source turn. All retained source turns are laid out using the current spacing. Point sources have zero width; uniform sources use the current width $\Delta t_n$ for the causal cell integral, including the current cell. The current and saved full-ring windows are checked against their own saved spacing and widths before evaluation. In particular, a Slicer’s observation window may follow integrated-clock boundaries and need not have duration $C/(\beta_n c)$. The solver deliberately remaps that window to $T_n$ for this approximation.

Stored source moments, emission velocities, physical times and widths are preserved. For response evaluation, both source and witness velocity factors use the current velocity, including the coupling of older sources. Thus this solver freezes the delay grid, integration widths and velocity coupling at their current values; it does not change the stored emission data. Missing turns contribute zero. With H previous turns, the complete snapshots n-H through n are retained, subject to causal ordering within the reconstructed grid. This is not a maximum-lag cutoff of $HC$: pairs in the oldest retained snapshot can have delays approaching $(H+1)T_n$.

This is a current-velocity approximation to physical-time history, useful when the revolution period changes little over the retained turns and the response is insensitive to the corresponding delay change. Compare with physical-time direct or converged time_fft results when acceleration or narrow-band phase sensitivity matters. There is no universal accuracy bound for collective growth or loss. FFT evaluates a zero-padded linear convolution with one inverse-transform normalization; this does not import an extra normalization or a distance cutoff from another code.

The complete retained source window is transformed on each call; old-source FFT work is not amortized as in a partitioned solver. The response spectrum can be reused while the current spacing, source shape and window length stay unchanged. For N bins and H previous turns the transform size grows with $(H+1)N$. Runtime depends on grid, history and active components, so selecting this solver does not guarantee a fixed speedup.

Stationary multibunch and long history

Set Solver="partitioned_fft", History="partitioned" and finite Memory turns=H. No modal fit is required for an arbitrary causal table. Define the sample-center times by

\[t_{n,b,i}=t_{\rm origin}+nT+bP+i\Delta t, \qquad K_{\ell,d,q}=\overline W(\ell T+dP+q\Delta t).\]

The grid fields are Period (s) T, Slots B, Slices S, Slot spacing (s) P, Slice spacing (s) delta-t, Origin (s) (default 0), Width (s) (default 0), and Projection (default exact). Period/spacings must be positive. Width must not exceed slice spacing; slot windows cannot overlap or span more than one period. Uniform source shape requires positive width; point shape requires zero width.

Slot and intra-slot indices are padded independently to at least 2B-1 and 2S-1. This is a linear, gapped convolution, even if P/delta-t is not an integer. Empty slots are zero; they still occupy their physical time positions. Source bins may be reordered or duplicated, and independent overlapping populations are summed conservatively. Times are mapped from the physical arrival clock, not from the enumeration order of bunches. Since arrival uses T_b-z/(beta_b*c), increasing harmonic IDs need not have increasing arrival times.

Projection="exact" requires the observed centers and widths to match this grid at every passage, up to floating-point roundoff. linear permits off-grid point sources within the declared windows: charge moments are distributed to two time nodes and fields interpolated back. This introduces a time-mesh approximation; refine the grid, especially near sharp wake features. The history algorithm adds no tail fitting, temporal decimation or coarsening. Changing revolution period, drifting outside the windows or incompatible widths raises an error. Choose time_fft for variable-period causal history with a converged physical-time mesh, or direct summation. There is no silent reset or change of history algorithm.

Uniform partitions schedule all H lag spectra each passage. Dyadic partitions cover lags [L,2L) for L=1,2,4,…, truncated at H. Each completed L-passage source block produces contributions only to future passages; no future beam trajectory is used. Single-lag partitions use spectral delay lines. With F padded spatial frequency cells, the history work is O(H F) per turn for uniform partitions and O(F log-squared H) amortized for dyadic partitions, in addition to spatial FFTs and component factors. Both retain O(H F) spectral storage. Dyadic scheduling has bursts at block boundaries; benchmark mean and maximum latency over at least one complete largest-block cycle, as well as the median.

The complexity bounds assume a fixed number of source channels and components. Each bunch uses its own reference event to convert its saved intervals. Portable checkpoints include the sampled response and grid fingerprint. Passage counters must be consecutive, including empty turns. A fresh run starts with zero past history.

For an equal-length Slicer on [-zmax,zmax], common beta, harmonic slots 0..B-1, circumference C, and constant reference speed, suppose slot b has reference passage time t0_b=(n-b/B)*C/(beta*c) at this wake point. An exact point grid is:

from PASS.para.schema import WakeSolverGroup, WakeConvolutionGrid
speed = beta * 299792458.0
grid = WakeConvolutionGrid(
    period=C/speed, slots=B, slices=S, slot_spacing=C/(B*speed),
    slice_spacing=2*zmax/(S*speed),
    origin=-((B-1)*C/B + zmax-zmax/S)/speed, width=0)
group = WakeSolverGroup(
    name="tabular_tail", solver="partitioned_fft", history="partitioned",
    source_shape="point", memory_turns=512, convolution_grid=grid,
    partition="dyadic", max_workspace_mb=2048, components=components)

Use the normal GPU backend to run the same configuration on CUDA. Particle storage may be float32; the declared physical mesh and wake arithmetic remain double precision. Projection membership near a slice edge can still differ with float32.

Variable-period general history

Solver="time_fft" uses fixed physical-time nodes $t_k=t_{\rm origin}+k\Delta t$, independently of revolution periods. Set History="partitioned", finite Memory time (s) and Time grid; leave Memory turns and Convolution grid unset. The input arrival clock supplies each passage’s actual times. Changing beta, bunch spacing, bin width or revolution period does not rescale or discard the existing history. The previously stated response/velocity approximations still apply: this algorithm does not derive a general two-time electromagnetic response.

Point source moments are deposited linearly onto neighboring time nodes. For finite uniform bins, deposition integrates the same hat basis over the source interval, conserving each coupled source moment. Fields are linearly interpolated to witness times. Within half the source width plus two mesh steps of a source center, the exact source-averaged response replaces its projected pair contribution. This local correction preserves the causal jump and half self-wake, including sources from the preceding passage. Far-field projection remains an approximation. Point sources and witnesses exactly on the mesh recover the corresponding discrete direct sum up to floating-point error.

Resolve short response features and high frequencies by refining Step (s). Converge the physical slice count and memory duration separately. Table knots and a sharp memory cutoff can limit the observed order of convergence; no universal error tolerance follows just from selecting time_fft. The step also must be resolvable by the absolute floating-point arrival clock.

Sources contain only particles that have already passed; no future trajectory is needed. CPU/GPU checkpoints preserve the unfinished block, near-correction sources, clock origin, and completed history. Empty passages also advance the passage counter.

For block size B, horizon H seconds and M=ceil(H/(B*delta-t))+1 history blocks, dyadic work per completed block is O(B log B + B log-squared M) amortized, plus source deposition, witness interpolation and local pair correction; storage is O(B M) for a fixed number of channels/components. One passage may span several blocks. Fine meshes also represent empty time between bunches, so partitioned_fft can be substantially cheaper for a stationary sparse train. Large overlapping source widths can increase local pair work. Block size changes scheduling and memory traffic, not physical resolution. Benchmark full largest-block cycles including peak latency.

from PASS.para.schema import WakeSolverGroup, WakeTimeGrid
group = WakeSolverGroup(
    name="accelerating_tail", solver="time_fft", history="partitioned",
    source_shape="uniform", memory_time=200e-6,
    time_grid=WakeTimeGrid(step=0.5e-9, block_size=1024),
    partition="dyadic", max_workspace_mb=2048, components=components)

These mesh values are illustrative and require convergence for the supplied wake. With a null origin, the first source interval chooses a nearby origin; an explicit origin must not follow the first source support. Source batches must remain causally ordered and nonoverlapping across calls, including bin widths. Independent overlapping populations inside one batch are permitted.

Numerical precision and convergence

Particle coordinates may use float32 or float64; physical arrival times, source charge moments, responses, modal states, and energy/momentum conversions use float64. GPU summation order may differ, so CPU/GPU results require numerical tolerances. Float32 storage can still change slice membership near a boundary and accumulate long-term transport rounding.

Equal-length z intervals are converted to time grids with the current bunch reference speed; changing that speed changes the time widths. The user controls Slicer update frequency. Check convergence independently in slice widths, response bandwidth, memory horizon, and time-grid spacing.

Recursive/modal passage windows may touch. CPU and GPU allow floating-point roundoff at their shared boundary, treating a negative time step within that tolerance as zero; actual backwards passage ordering remains an error. With finite Memory time (s), bins entirely inside the horizon retain the model’s untruncated bin-average formula. Only bins crossing the horizon require a partial integral, and bins wholly beyond it contribute zero.

Physical scope and conventions

PASS tracks supplied or analytic response models. It does not derive the response of arbitrary three-dimensional structures by solving Maxwell’s equations. The reference-velocity approximation within each bunch is retained when evaluating a response’s velocity coupling. This is distinct from the exact incoming particle speed used to convert transverse voltage to momentum impulse.

The continuous particle coordinate is $z_i=\beta_b c(T_b-t_i)$. At this location, the physical arrival time is

\[t_i=T_b-z_i/(\beta_b c).\]

No arrival correction is stored. RF reference-energy changes scale z to preserve this time; regrouping transforms z and momenta into the destination reference. The wake adapter converts the latest user-supplied z intervals: centers are $T_b-z_{slice}/(\beta_b c)$ and widths are $\Delta z/(\beta_b c)$. RF does not alter saved intervals or membership. Stored emitted snapshots retain their sampled physical times and widths; later reference changes do not alter those records. Physical-time solvers evaluate them without reinterpretation. The explicitly selected quasistatic_fft approximation instead reconstructs delays, widths and velocity coupling from the current reference, as described above. See Longitudinal coordinate and reference time.

The canonical frequency convention is

\[F(f)=\int W(t)e^{-2\pi i f t}\,dt,\qquad Z_\parallel=F,\qquad Z_\perp=iF.\]

For source/test monomial powers of total order $n$, integrated wake units are V/C/mⁿ and impedance units are ohm/mⁿ. Source moments use signed real charge represented by each macro particle; witness macro weight cancels. Positive longitudinal wake means energy loss. Positive transverse voltage means positive Lorentz force. PASS updates energy per nucleon by $\Delta E=-Z_{\mathrm{ion}}V_\parallel/A$, then computes momentum exactly. The transverse kick uses incoming particle $\beta_i$: $\Delta p_x=(Z_{\mathrm{ion}}/A)V_x/(\beta_i p_0)$.

Causal kernels use half of a finite jump at zero delay. A uniform source represents constant charge density over the slice’s full time width (the reconstructed current width for quasistatic_fft); its kernel is integrated analytically or through its primitive. point sources are at the slice centers. Slicing convergence and parameter scans are user-controlled; there is no automatic slice-error controller.

Velocity and acceleration

Each component declares Velocity:

Kind="fixed", Beta: stationary response at one common reference speed. A different reference speed is rejected, including changes during tracking.
Kind="factorized", increasing Betas and matching real Source and Witness tables: $W(t;\beta_s,\beta_w)=g_s(\beta_s)W_0(t)g_w(\beta_w)$. Linear interpolation is restricted to the supplied beta interval. Physical-time history uses the source speed at that passage and applies the current witness factor when observing the stored field. quasistatic_fft instead evaluates both factors at the current reference speed, including all retained source turns.
Kind="ideal" explicitly defines a velocity-independent point-response coupling. This is a model assumption, not an inferred transit-time correction for a physical cavity.

The finite-beta wall sets its matching fixed velocity automatically. A single stationary spectrum cannot determine arbitrary unequal-velocity trajectories, complex transit phases or arbitrary acceleration. Factorized real coupling supports acceleration only when that factorization is supplied and valid; pole frequencies and damping remain fixed. No universal beta multiplier is applied.

Raw spectra and fitting

The raw route integrates the piecewise-linear spectrum with an oscillatory quadrature, preserving nonuniform frequency samples and avoiding an artificial periodic FFT time window. Values outside the measured band are explicitly zero. A finite-band inverse is two-sided even for a causal underlying system. Reconstruction="two_sided" retains it. causal_projection explicitly sets its negative-time part to zero and uses half the projected jump at zero; this changes the effective frequency response and is a bandwidth approximation. Frequency bandwidth and spacing require independent convergence checks.

Fitting uses variable projection: nonlinear optimization of user-selected poles and real least squares for residues. It does not select the number of modes. The original spectrum and fit diagnostics remain available on the fitted model. The fit must satisfy the specified maximum relative error, normalized with the specified relative floor. Stability follows the selected pole half-planes; passivity is not automatically enforced or certified. Scalar longitudinal passivity tests cannot be applied indiscriminately to transverse components. No instantaneous delta/derivative feedthrough is inferred from missing bandwidth.

Right-half-plane poles describe a decaying backward spatial branch. They are never advanced as a growing temporal state. causal_projection fits require left-half-plane initial poles. General two-sided fits use two_sided and an explicit spatial boundary. Electromagnetic-simulation project files are not read directly; numeric exports can use the explicit file conventions described on this page.

Custom spatial terms

In addition to predefined named components, Component="custom" requires Spatial containing Plane (x/y/z), Source powers [a,b] and Test powers [c,d], all nonnegative integers. The projected source moment is $\sum_j q_j x_j^a y_j^b$; its response is multiplied by witness $x_i^c y_i^d$. The kernel unit order is a+b+c+d. A custom term specifies one supplied polynomial response; it does not derive unprovided multipoles or enforce cross-component Maxwell constraints. The round-wall analytic model retains its explicitly supported longitudinal/diagonal dipolar components.

CPU and GPU support the same nonnegative integer powers.

Slice coordinates and response boundaries

WakeField accepts local Coordinate=z_rel intervals and the separate Coordinate=arrival_phase coasting projection. WakeField rejects the Coordinate=z_periodic circumference-folded slices required by SpaceCharge, because their centers do not preserve continuous arrival times. Use separate named slice sets. The latest explicit Slicer result controls membership and geometry. Coordinate selection does not change the algorithm group’s Boundary: periodic is a repeated steady spatial response; evolving passage history uses causal_passages. Timing uses float64 and the stored continuous z.