DistMonitor

DistMonitor saves a complete particle snapshot at selected turns and at one lattice position. It is intended for post-processing the full bunch distribution, including particles that have already been lost.

Code location: PASS/commands/monitor/distribution.py
Registered command: "distmonitor"
Output directory: output_dir_dist (the distribution subdirectory of the run output)

Turn selection

Save turns is a list of one-element or three-element lists. A one-element list selects one zero-based turn. A three-element list is [start, end, step] and selects start, start + step, ... up to and including end. Multiple entries may be supplied; overlapping entries are merged automatically.

For example:

"distribution_1": {
    "S (m)": 12.5,
    "Command": "DistMonitor",
    "Save turns": [[0], [100, 200, 10], [500, 1000, 100]]
}

An empty list, "Save turns": [], disables saving. step must be positive. If a range extends beyond the simulation, an end above the last turn is clipped to num_turns - 1 with a warning. A range whose start is at or beyond num_turns is ignored with a warning; a negative start is clipped to zero. Malformed ranges and non-positive steps remain errors. The monitor compiles the selection into a byte table during initialization; checking the current turn is a single bounds check and table lookup.

Interface

Python field	JSON key	Type	Description
`s`	`"S (m)"`	float	Longitudinal position of the monitor.
`command`	`"Command"`	str	Must be `"DistMonitor"` (case-insensitive at runtime).
`save_turns`	`"Save turns"`	list[list[int]]	Single turns `[turn]` or inclusive ranges `[start, end, step]`.

The sequence key supplies the monitor name. With the high-level API, the schema object can be used directly:

from PASS.para.schema.monitors import DistMonitor

monitor = DistMonitor(s=12.5, save_turns=[[0], [100, 200, 10]])

Output

One TFS file is written for each selected turn and each bunch. The filename contains the run time, beam and bunch identifiers, monitor position, monitor name, and turn number. All particles in the bunch are written, regardless of the sign of tag.

The data columns are:

Column	Unit	Description
`x`, `px`, `y`, `py`	m or normalized momentum	Transverse phase-space coordinates.
`z`	m	Tracked bunch-relative coordinate `z_rel`.
`dp`		Relative momentum deviation.
`tag`		Particle identifier; positive means alive and negative means lost.
`lost_turn`		Turn at which the particle was lost (`-1` if it was not lost).
`lost_position`	m	Longitudinal loss position (`-1` if it was not lost).

Headers include S, command and monitor names, beam/bunch identifiers, Turn, particle counts, backend and precision, PASS version, timestamp, ZCoordinate, ZCenter, and Circumference. The z column is not folded or shifted while saving; use ZCenter when reconstructing a lab-frame coordinate.

CPU and GPU behavior

On CPU, the monitor writes directly from the NumPy particle arrays. On GPU, only the nine output fields are copied to host memory at a selected turn and the host copy is passed to the TFS writer. No history buffer is retained between turns, so memory use is proportional to one particle snapshot rather than to num_turns snapshots.