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

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

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

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])

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

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

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)

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

Check if the entry of the file contains BPM data.

static map_bpm_name(key: str) → str

Convert the given key to a BPM name.

class turn_by_turn.iota.Version(*values)

class turn_by_turn.iota.VersionOneReader(path: Path)

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

static is_bpm_key(key: str, plane: Literal['X', 'Y'] | None = None) → bool

Check if the entry of the file contains BPM data.

static map_bpm_name(key: str) → str

Convert the given key to a BPM name.

class turn_by_turn.iota.VersionTwoReader(path: Path)

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

Check if the entry of the file contains BPM data.

static map_bpm_name(key: str) → str

Convert the given key to a BPM name.

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

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

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

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

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

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)

Parameters read from the first turn of the file.

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

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]

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]

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

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

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

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.