ASCII

Data handling for the special turn-by-turn ASCII files, that were used in the past. They are not SDDS files, but instead more like table, containing the columns: - Plane (0 for horizontal, 1 for vertical) - Observation point (i.e. BPM name) - BPM index/longitunial location - Value Turn 1, Turn 2, etc.

turn_by_turn.ascii.is_ascii_file(file_path: str | Path) → bool[source]

Returns True only if the file looks like a readable TbT ASCII file, else False.

Parameters:: file_path (str | Path) -- path to the turn-by-turn measurement file.
Returns:: A boolean.

turn_by_turn.ascii.read_ascii(file_path: str | Path, bunch_id: int | None = None) → TbtData

Reads turn-by-turn data from an ASCII turn-by-turn format file, and return the date as well as parsed matrices for construction of a TbtData object.

Parameters:

file_path (str | Path) -- path to the turn-by-turn measurement file.
bunch_id (int, optional) -- the bunch id associated with this file. Defaults to None, but is then attempted to parsed from the filename. If not found, 0 is used.

Returns:

Turn-by-turn data

turn_by_turn.ascii.read_tbt(file_path: str | Path, bunch_id: int | None = None) → TbtData[source]

Reads turn-by-turn data from an ASCII turn-by-turn format file, and return the date as well as parsed matrices for construction of a TbtData object.

Parameters:

file_path (str | Path) -- path to the turn-by-turn measurement file.
bunch_id (int, optional) -- the bunch id associated with this file. Defaults to None, but is then attempted to parsed from the filename. If not found, 0 is used.

Returns:

Turn-by-turn data

turn_by_turn.ascii.write_ascii(output_path: str | Path, tbt_data: TbtData) → None

Write a TbtData object’s data to file, in the TbT ASCII format.

Parameters:

output_path (str | Path) -- path to the disk location where to write the data.
tbt_data (TbtData) -- the TbtData object to write to disk.

turn_by_turn.ascii.write_tbt(output_path: str | Path, tbt_data: TbtData) → None[source]

Write a TbtData object’s data to file, in the TbT ASCII format.

Parameters:

output_path (str | Path) -- path to the disk location where to write the data.
tbt_data (TbtData) -- the TbtData object to write to disk.

DOROS

Data handling for turn-by-turn measurement files from the DOROS BPMs of the LHC (files in hdf5 format).

The file contains entries for METADATA, TIMESTAMPS_INDEX and TIMESTAMPS_TABLE, which we do not use and then the actual data per BPM.

These entries are as follows:

The timetamps in microseconds.
- bstTimestamp: timestamp of the trigger
- acqStamp: tiemstamp of the actual acquisition
Position/Orbit entries are the average position of the beam per turn, i.e. the turn-by-turn data averaged over all bunches, as DOROS cannot distinguish between the bunches.
- nbOrbitSamplesRead: number of orbit samples read
- horPositions: horizontal position of the beam per turn
- verPositions: vertical position of the beam per turn
Oscillation entries are the frequencies of change in position.
nbOscillationSamplesRead: number of oscillation samples read
horOscillationData: horizontal oscillation data
verOscillationData: vertical oscillation data

class turn_by_turn.doros.DataKeys(default_value: float, n_samples: str, names: dict[str, str])[source]: Class to handle the different entry keys for oscillations and positions.

turn_by_turn.doros.read_tbt(file_path: str | Path, bunch_id: int = 0, data_type: str = 'oscillations') → TbtData[source]

Reads turn-by-turn data from the DOROS’s SDDS format file.

Parameters:

file_path (Union[str, Path]) -- path to the turn-by-turn measurement file.
bunch_id (int, optional) -- the ID of the bunch in the file. Defaults to 0.
data_type (str) -- Datatype to load. Defaults to “oscillations”.

Returns:

A TbTData object with the loaded data.

turn_by_turn.doros.write_tbt(file_path: str | Path, tbt_data: TbtData, data_type: str = 'oscillations') → None[source]

Writes turn-by-turn data to the DOROS’s SDDS format file.

Parameters:

tbt_data (TbtData) -- data to be written
file_path (Union[str, Path]) -- path to the turn-by-turn measurement file.

Iota

Data handling for turn-by-turn measurement files from Iota (files in hdf5 format).

class turn_by_turn.iota.AbstractIotaReader(path: Path)[source]

Class that reads the IOTA turn-by-turn data.

This abstract class implements the whole reading in its __init__, but cannot run by itself, as the version specific functions (see below) need to be implemented first.

The read data is stored as TbtData-object in the tbt_data attribute.

static is_bpm_key(key: str, plane: Literal['X', 'Y'] | None = None) → bool[source]: Check if the entry of the file contains BPM data.

static map_bpm_name(key: str) → str[source]: Convert the given key to a BPM name.

class turn_by_turn.iota.Version(*values)[source]

class turn_by_turn.iota.VersionOneReader(path: Path)[source]

Version 1 contains three keys per BPM: X, Y and Intensity.

static is_bpm_key(key: str, plane: Literal['X', 'Y'] | None = None) → bool[source]: Check if the entry of the file contains BPM data.

static map_bpm_name(key: str) → str[source]: Convert the given key to a BPM name.

class turn_by_turn.iota.VersionTwoReader(path: Path)[source]

Version 2 contains a single key per BPM, which contains data for both planes (and possibly more which we ignore).

static is_bpm_key(key: str, plane: Literal['X', 'Y'] | None = None) → bool[source]: Check if the entry of the file contains BPM data.

static map_bpm_name(key: str) → str[source]: Convert the given key to a BPM name.

turn_by_turn.iota.read_tbt(file_path: str | Path, version: Version = Version.two) → TbtData[source]

Reads turn-by-turn data from IOTA’s hdf5 format file. Beware, that there are two possible versions of the iota-HDF5 format.

Parameters:

file_path (Union[str, Path]) -- path to the turn-by-turn measurement file.
version (int) -- the format version to use when reading the written file. Defaults to the latest one, currently 2.

Returns:

A TbTData object with the loaded data.

LHC

Data handling for turn-by-turn measurement files from the LHC (files in SDDS format).

turn_by_turn.lhc.read_tbt(file_path: str | Path) → TbtData[source]

Reads turn-by-turn data from the LHC’s SDDS format file. Will first determine if it is in ASCII format to figure out which reading method to use.

Parameters:: file_path (Union[str, Path]) -- path to the turn-by-turn measurement file.
Returns:: A TbTData object with the loaded data.

turn_by_turn.lhc.write_tbt(output_path: str | Path, tbt_data: TbtData) → None[source]

Write a TbtData object’s data to file, in the LHC’s SDDS format.

Parameters:

output_path (Union[str, Path]) -- path to a the disk location where to write the data.
tbt_data (TbtData) -- the TbtData object to write to disk.

SPS

Data handling for turn-by-turn measurement files from the SPS (files in SDDS format).

turn_by_turn.sps.read_tbt(file_path: str | Path, remove_trailing_bpm_plane: bool = True) → TbtData[source]

Reads turn-by-turn data from the SPS’s SDDS format file. Will first determine if it is in ASCII format to figure out which reading method to use.

Parameters:

file_path (str | Path) -- path to the turn-by-turn measurement file.
remove_trailing_bpm_plane (bool, optional) -- if True, will remove the trailing BPM plane (‘.H’, ‘.V’) from the BPM-names. This makes the measurement data compatible with the madx-models. Defaults to True.

Returns:

A TbTData object with the loaded data.

turn_by_turn.sps.write_tbt(output_path: str | Path, tbt_data: TbtData, add_trailing_bpm_plane: bool = True) → None[source]

Write a TbtData object’s data to file, in a SPS’s SDDS format. The format is reduced to the minimum parameters used by the reader.

WARNING: This writer uses 0 for horizontal and 1 for vertical BPMs: in the MonPlanes array, i.e. the pre-2025 format.

Parameters:

output_path (str | Path) -- path to a the disk location where to write the data.
tbt_data (TbtData) -- the TbtData object to write to disk.
add_trailing_bpm_plane (bool, optional) -- if True, will add the trailing BPM plane (‘.H’, ‘.V’) to the BPM-names. This assures that all BPM-names are unique, and that the measurement data is compatible with the sdds files from the FESA-class. WARNING: If present, these will be used to determine the plane of the BPMs, otherwise the MonPlanes array will be used. Defaults to True.

PTC

Data handling for turn-by-turn measurement files from the PTC code, which can be obtained by performing particle tracking of your machine through the MAD-X PTC interface. The files are very close in structure to TFS files, with the difference that the data part is split into “segments” relating containing data for a given observation point.

class turn_by_turn.ptc.Segment(number, turns, particles, element, name)

element: Alias for field number 3

name: Alias for field number 4

number: Alias for field number 0

particles: Alias for field number 2

turns: Alias for field number 1

class turn_by_turn.ptc.TbTParams(bpms: list[str] = <factory>, particles: list[int] = <factory>, column_indices: dict[~typing.Any, ~typing.Any] | None=None, n_turns: int = 0, n_particles: int = 0)[source]: Parameters read from the first turn of the file.

turn_by_turn.ptc.read_tbt(file_path: str | Path) → TbtData[source]

Reads turn-by-turn data from the PTC trackone format file.

Parameters:: file_path (Union[str, Path]) -- path to the turn-by-turn measurement file.
Returns:: A TbTData object with the loaded data.

Trackone

Data handling for turn-by-turn measurement files from the MAD-X code, which can be obtained by performing particle tracking of your machine through in MAD-X. The files are very close in structure to TFS files, with the difference that the data part is split into “segments” relating containing data for a given observation point.

turn_by_turn.trackone.get_structure_from_trackone(nturns: int = 0, npart: int = 0, file_path: str | Path = 'trackone') → tuple[ndarray, ndarray][source]

Extracts BPM names and particle coordinates in the trackone file produced by MAD-X.

Parameters:

nturns (int) -- Number of turns tracked in the trackone, i.e. obtained from get_trackone_stats().
npart (int) -- Number of particles tracked in the trackone, i.e. obtained from get_trackone_stats().
file_path (Union[str, Path]) -- path to the turn-by-turn measurement file.

Returns:

A numpy array of BPM names and a 4D Numpy array [quantity, BPM, particle/bunch No., turn No.] quantities in order [x, px, y, py, t, pt, s, E].

turn_by_turn.trackone.get_trackone_stats(file_path: str | Path, write_out: bool = False) → tuple[int, int][source]

Determines the number of particles and turns in the matrices from the provided MAD-X trackone file.

Parameters:

file_path (Union[str, Path]) -- path to the turn-by-turn measurement file.
write_out (bool) -- if True, write out the determined stats to a stats.txt file.

Returns:

A tuple with the number of turns and particles.

turn_by_turn.trackone.read_tbt(file_path: str | Path, is_tracking_data: bool = False) → TbtData[source]

Reads turn-by-turn data from the MAD-X trackone format file.

Parameters:

file_path (Union[str, Path]) -- path to the turn-by-turn measurement file.
is_tracking_data (bool) -- if True, all (X, PX, Y, PY, T, PT, S, E) fields are expected in the file as it is considered a full tracking simulation output. Those are then read into TrackingData objects. Defaults to False.

Returns:

A TbTData object with the loaded data.

SuperKEKB

Data handling for turn-by-turn measurement files from SuperKEKB taken by the application in the control room. The file format is similar to Mathematica or some json and be parsed easily with regex. The extension is usually .data.

turn_by_turn.superkekb.read_tbt(file_path: str | Path) → TbtData[source]

Reads turn-by-turn data from the SuperKEKB’s measurement file.

Parameters:: file_path (Union[str, Path]) -- path to the turn-by-turn measurement file.
Returns:: A TbTData object with the loaded data.

turn_by_turn.superkekb.write_tbt(file_path: str | Path, tbt_data: TbtData) → None[source]

Writes turn-by-turn data to a SuperKEKB’s measurement file.

Parameters:

file_path (Union[str, Path]) -- path to the output turn-by-turn measurement file.
tbt_data (TbtData) -- turn-by-turn data to write.

MAD-NG

This module provides functions to read and write turn-by-turn measurement data produced by the MAD-NG code. MAD-NG stores its tracking data in the TFS (Table File System) file format.

Data is loaded into the standardised TbtData structure used by turn_by_turn, allowing easy post-processing and conversion between formats.

Dependencies:

Requires the tfs-pandas >= 4.0.0 package for compatibility with MAD-NG features. Earlier versions does not support MAD-NG TFS files.

turn_by_turn.madng.convert_to_tbt(df: pd.DataFrame | tfs.TfsDataFrame) → TbtData[source]

Convert a TFS or pandas DataFrame to a TbtData object.

This function parses the required turn-by-turn columns, reconstructs the particle-by-particle tracking data, and returns a TbtData instance that can be written or converted to other formats.

Parameters:

df (pd.DataFrame | TfsDataFrame) -- DataFrame containing MAD-NG turn-by-turn tracking data.

Returns:

The extracted and structured turn-by-turn data.

Return type:

TbtData

Raises:

TypeError -- If the input is not a recognised DataFrame type.
ValueError -- If the data structure is inconsistent (e.g., lost particles).

turn_by_turn.madng.read_tbt(file_path: str | Path) → TbtData[source]

Read turn-by-turn data from a MAD-NG TFS file.

Loads the TFS file using tfs-pandas and converts its contents into a TbtData object for use with the turn_by_turn toolkit.

Parameters:: file_path (str | Path) -- Path to the MAD-NG TFS measurement file.
Returns:: The loaded turn-by-turn data.
Return type:: TbtData
Raises:: ImportError -- If the tfs-pandas package is not installed.

turn_by_turn.madng.write_tbt(output_path: str | Path, tbt_data: TbtData) → None[source]

Write turn-by-turn data to a MAD-NG TFS file.

Takes a TbtData object and writes its contents to disk in the standard TFS format used by MAD-NG, including relevant headers (date, time, origin).

Parameters:

output_path (str | Path) -- Destination file path for the TFS file.
tbt_data (TbtData) -- The turn-by-turn data to write.

Raises:

ImportError -- If the tfs-pandas package is not installed.

XTrack TbT Conversion from Lines

Helpers to convert data produced by the xtrack tracking framework into the turn_by_turn TbtData format.

This module converts monitor data from xtrack into the corresponding TbtData representation. It currently supports data produced by:

xtrack.MultiElementMonitor recorded via xtrack.Line.record_multi_element_last_track.
One or more xtrack.ParticlesMonitor elements placed in the line.

The appropriate converter is selected based on which monitor data are present on the provided xtrack.Line. If multi-element monitor data are available, they are preferred; otherwise particle monitor data are used.

turn_by_turn.xtrack.converter.convert_to_tbt(xline: Line) → TbtData[source]

Convert tracking results from an xtrack.Line into a TbtData object.

Dispatches to one of the specific converters in turn_by_turn.xtrack depending on which monitor data is available in the provided Line.

Supported source datatypes and resulting TbtData.meta['source_datatype'] values:

xtrack_multi_element_monitor: when converting from an
xtrack.MultiElementMonitor (via record_multi_element_last_track).
xtrack_particle_monitors: when converting from one or more
xtrack.ParticlesMonitor elements.

Parameters:

xline (Line) -- An xtrack.Line containing monitor data.

Returns:

The extracted turn-by-turn data. The meta mapping contains a source_datatype key describing the origin of the data.

Return type:

TbtData

Raises:

ImportError -- If the xtrack package is not installed.
TypeError -- If the input is not an xtrack.Line.
ValueError -- If no suitable monitor data is found on the provided Line.

turn_by_turn.xtrack.converter.read_tbt(path: str | Path) → None[source]

Not implemented.

Reading TBT data directly from files is not supported for xtrack. Use convert_to_tbt to convert an in-memory xtrack.Line instead.

XTrack TbT Conversion from Multi-Element Monitor

Convert Xsuite MultiElementMonitor output into TbtData. Reference: https://xsuite.readthedocs.io/en/latest/track.html#multi-element-monitor

Usage

Track with multi_element_monitor_at:

import xtrack as xt
# place a MultiElementMonitor in the line via the xtrack API
monitor_names = ["BPM1", "BPM2", "BPM3"]
line.track(
     particles,
     num_turns=1024,
     multi_element_monitor_at=monitor_names,
)

Convert to turn_by_turn data:

from turn_by_turn.xtrack import convert_to_tbt

tbt = convert_to_tbt(line)

Notes

Data is read from line.record_multi_element_last_track.
The converter expects arrays with shape (turn, particle, obs) from monitor.get("x") and monitor.get("y").
Output order follows the order of monitor names provided to multi_element_monitor_at, independent of the order in which they appear in the line.

turn_by_turn.xtrack._multi_element_monitor.convert_to_tbt(xline: xt.Line) → TbtData[source]

Convert xtrack multi-element monitor data to TbtData.

Parameters:: xline (xt.Line) -- Tracked line containing record_multi_element_last_track.
Returns:: Turn-by-turn data for each particle and observed element.
Return type:: TbtData
Raises:: ValueError -- If monitor data is missing, or has unexpected shape.

turn_by_turn.xtrack._multi_element_monitor.is_line_suitable_for_conversion(xline: xt.Line) → bool[source]

Check if the given xtrack Line is suitable for conversion to TbtData.

This function verifies that the Line contains a non None multi-element monitor data.

Parameters:: xline (xt.Line) -- The xtrack Line to check.
Returns:: True if the Line is suitable for conversion, False otherwise.
Return type:: bool

XTrack TbT Conversion from Particle Monitors

Convert tracking results produced by one or more xtrack.ParticlesMonitor elements into the standardised TbtData format used by turn_by_turn.

Usage

from turn_by_turn.xtrack import convert_to_tbt

# after building particles and tracking a line containing # xt.ParticlesMonitor elements, convert to TbtData: tbt = convert_to_tbt(line)

Prerequisites for using convert_to_tbt:

The input Line must contain one or more ParticlesMonitor elements
positioned at each location where turn-by-turn data is required (e.g., all BPMs).

A valid monitor setup involves:
- Placing a xt.ParticlesMonitor instance in the line’s element sequence
  at all the places you would like to observe.
- Configuring each monitor with identical settings:
  start_at_turn (first turn to record, usually 0)
  
  stop_at_turn (The total number of turns to record, e.g., 100)
  
  num_particles (number of tracked particles)
If any monitor is configured with different parameters, convert_to_tbt will either find no data or raise an inconsistency error.

Also, if you specify more turns than were actually tracked, the resulting TBT data will include all turns up to the monitor’s configured limit. This may result in extra rows filled with zeros for turns where no real data was recorded, which might not be desirable for your analysis.
Before conversion, you must:
- Build particles with the desired initial coordinates
  (using line.build_particles(...)).
- Track those particles through the line for the intended number of turns
  (using line.track(..., num_turns=num_turns)).

Once these conditions are met, pass the tracked Line to convert_to_tbt to extract the data from each particle monitor into a TbtData object.

turn_by_turn.xtrack._particle_monitors.convert_to_tbt(xline: Line) → TbtData[source]

Convert tracking results from an xtrack Line into a TbtData object.

This function extracts all ParticlesMonitor elements found in the Line, verifies they contain consistent turn-by-turn data, and assembles the results into the standard TbtData format. One TransverseData matrix is created per tracked particle.

Parameters:: xline (Line) -- An xtrack.Line containing at least one ParticlesMonitor.
Returns:: The extracted turn-by-turn data for all particles and monitors.
Return type:: TbtData
Raises:: ValueError -- If no monitors are found or data is inconsistent.

turn_by_turn.xtrack._particle_monitors.is_line_suitable_for_conversion(xline: Line) → bool[source]

Check if the given xtrack Line is suitable for conversion to TbtData.

This function verifies that the Line contains at least one ParticlesMonitor and that all monitors have consistent tracking data (same number of turns and particles).

Parameters:: xline (xt.Line) -- The xtrack Line to check.
Returns:: True if the Line is suitable for conversion, False otherwise.
Return type:: bool