PhaseAdvanceMonitor

PhaseAdvanceMonitor measures the uncoupled horizontal and vertical fractional tune of each macro particle at one fixed lattice location. It is the only phase-advance monitor API and replaces the former PhaseMonitor.

The monitor subtracts the configured closed orbit and horizontal dispersion, then uses fixed design optics to form

\[u_x = (x-x_{CO}-D_x\delta)/\sqrt{\beta_x},\qquad v_x = \alpha_x u_x + \sqrt{\beta_x}(p_x-p_{x,CO}-D'_x\delta).\]

The same construction is used in y without dispersion. From consecutive turns it accumulates the directed phase advance and writes only its equivalent fractional tune, sum(dmu)/(2 pi N). Phase itself is deliberately not an output field because it carries no additional information.

This monitor assumes uncoupled transverse optics. With x-y coupling its x/y values are projected tunes, not normal-mode tunes.

Configuration

Turn ranges accepts [start, end) pairs representing the zero-based left-closed, right-open interval [start, end). At least two turns are required. The value 0 (or an empty list) disables analysis, and Enable can disable the monitor without removing it from the sequence. Out-of-range endpoints are clipped to [0, num_turns].

"tune_1": {
    "S (m)": 12.5,
    "Command": "PhaseAdvanceMonitor",
    "Beta x (m)": 18.0,
    "Beta y (m)": 22.0,
    "Alpha x": -0.4,
    "Alpha y": 0.2,
    "Dx (m)": 1.1,
    "Dpx": 0.03,
    "X CO (m)": 0.0,
    "PX CO": 0.0,
    "Y CO (m)": 0.0,
    "PY CO": 0.0,
    "Enable": true,
    "Turn ranges": [[0, 1024]]
}

Dx, Dpx and all closed-orbit fields default to zero. Min action is optional; it excludes a sample when its normalized action is too small for a stable angle. The precision-specific default is 5e-17 for float64 and 5e-9 for float32.

Output

One TFS file is written for each beam, bunch, monitor, and completed window in the tuneSpread output directory. Rows remain separate by bunch and include lost particles. Columns are tag, tuneXFractional, tuneYFractional, per-plane interval counts, validX/Y, completeX/Y, and loss metadata. valid means at least one accepted interval while the particle remains alive; complete means every interval in the window was accepted. Lost particles are never included in phase accumulation.

Headers record the complete fixed optical reference, window endpoints, expected interval count, backend, precision, and PASSVersion.