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.

ESRF

Data handling for turn-by-turn measurement files from ESRF (files in matlab format). This module is untested and should be considered experimental at the moment.

turn_by_turn.esrf.load_esrf_mat_file(infile: str | Path) → Tuple[ndarray, ndarray]

Reads the ESRF TbT Matlab file, checks for nans and matrices duplicities from consecutive kicks.

Parameters:

infile (Union[str, Path]) -- path to the turn-by-turn measurement file.

Returns:

A 1D numpy array of BPM names and a 4D Numpy array [quantity, BPM, particle/bunch No., turn No.] quantities in order [x, y]

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

Reads turn-by-turn data from the ESRF’s Matlab format file.

Parameters:

file_path (Union[str, Path]) -- path to the turn-by-turn measurement file.

Returns:

A TbTData object with the loaded data.

Iota

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

turn_by_turn.iota.read_tbt(file_path: str | Path, hdf5_version: int = 2) → TbtData

Reads turn-by-turn data from IOITA’s hdf5 format file. As there are 2 possible versions of the HDF5 format, this will try them both successively.

Parameters:

• file_path (Union[str, Path]) -- path to the turn-by-turn measurement file.

• hdf5_version (int) -- the HDF5 format version to use when reading the written file. Defaults to the latest, a.k.a 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 (Union[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 necessary parameters used by the reader.

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.

• 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. 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

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.

MAD-NG

This module provides functions to read and write MAD-NG turn-by-turn measurement files. These files are in the TFS format.

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

Reads turn-by-turn data from the MAD-NG TFS format file.

Parameters:

file_path (str | Path) -- path to the turn-by-turn measurement file.

Returns:

A TbTData object with the loaded data.

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

Writes turn-by-turn data to a TFS file for MAD-NG.

Parameters:

• tbt_data (TbtData) -- Turn-by-turn data to write.

• file_path (str | Path) -- Target file path.