Constants

Specific constants to be used in turn_by_turn, to help with consistency.

IO

This module contains high-level I/O functions to read and write tur-by-turn data objects in different formats. While data can be loaded from the formats of different machines / codes, each format getting its own reader module, writing functionality is at the moment always done in the LHC’s SDDS format.

turn_by_turn.io.read_tbt(file_path: str | Path, datatype: str = 'lhc') → TbtData

Calls the appropriate loader for the provided matrices type and returns a TbtData object of the loaded matrices.

Parameters:

• file_path (Union[str, Path]) -- path to a file containing TbtData.

• datatype (str) -- type of matrices in the file, determines the reader to use. Case-insensitive, defaults to lhc.

Returns:

A TbtData object with the loaded matrices.

turn_by_turn.io.write_tbt(output_path: str | Path, tbt_data: TbtData, noise: float | None = None, seed: int | None = None, datatype: str = 'lhc') → 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.

• noise (float) -- optional noise to add to the data.

• seed (int) -- A given seed to initialise the RNG if one chooses to add noise. This is useful to ensure the exact same RNG state across operations. Defaults to None, which means any new RNG operation in noise addition will pull fresh entropy from the OS.

• datatype (str) -- type of matrices in the file, determines the reader to use. Case-insensitive, defaults to lhc.

Structures

Data structures to be used in turn_by_turn to store turn-by-turn measurement data.

class turn_by_turn.structures.TbtData(matrices: Sequence[TransverseData | TrackingData], date: datetime | None = None, bunch_ids: List[int] | None = None, nturns: int | None = None)

Object holding a representation of a Turn-by-Turn data measurement. The date of the measurement, the transverse data, number of turns and bunches as well as the bunch IDs are encapsulated in this object.

class turn_by_turn.structures.TrackingData(X: DataFrame, PX: DataFrame, Y: DataFrame, PY: DataFrame, T: DataFrame, PT: DataFrame, S: DataFrame, E: DataFrame)

Object holding multidimensional turn-by-turn simulation data in the form of pandas DataFrames.

classmethod fieldnames() → List[str]

Return a list of the fields of this dataclass.

class turn_by_turn.structures.TransverseData(X: DataFrame, Y: DataFrame)

Object holding measured turn-by-turn data for both transverse planes in the form of pandas DataFrames.

classmethod fieldnames() → List[str]

Return a list of the fields of this dataclass.

Utils

Utility functions for convenience operations on turn-by-turn data objects in this package.

turn_by_turn.utils.add_noise(data: ndarray, noise: float | None = None, sigma: float | None = None, seed: int | None = None) → ndarray

Returns the given data with added noise. Noise is generated as a standard normal distribution (mean=0, standard_deviation=1) with the size of the input data, and scaled by the a factor before being added to the provided data. Said factor can either be provided, or calculated from the input data’s own standard deviation.

Parameters:

• data (np.ndarray) -- your input data.

• noise (float) -- the scaling factor applied to the generated noise.

• sigma (float) -- if provided, then that number times the standard deviation of the input data will be used as scaling factor for the generated noise.

• seed (int) -- a given seed to initialise the RNG.

Returns:

A new numpy array with added noise to the provided data.

turn_by_turn.utils.add_noise_to_tbt(data: TbtData, noise: float | None = None, sigma: float | None = None, seed: int | None = None) → TbtData

Returns a new copy of the given TbT data with added noise. The noise is generated by turn_by_turn.utils.add_noise() from a single rng, i.e. the noise is not repeated on each dataframe.

Parameters:

• data (TbtData) -- your input TbT-data.

• noise (float) -- the scaling factor applied to the generated noise.

• sigma (float) -- if provided, then that number times the standard deviation of the input data will be used as scaling factor for the generated noise.

• seed (int) -- a given seed to initialise the RNG.

Returns:

A copy of the TbtData with noised data on all matrices.

turn_by_turn.utils.generate_average_tbtdata(tbtdata: TbtData) → TbtData

Takes a TbtData object and returns another containing the averaged matrices over all bunches/particles at all used BPMs.

Parameters:

tbtdata (TbtData) -- entry TbtData object from measurements.

Returns:

A new TbtData object with the averaged matrices.

turn_by_turn.utils.get_averaged_data(bpm_names: Sequence[str], matrices: Sequence[TransverseData], plane: str, turns: int) → ndarray

Average data from a given plane from the matrices of a TbtData.

Parameters:

• bpm_names (Sequence[str]) --

• matrices (Sequence[TransverseData]) -- matrices from a TbtData object.

• plane (str) -- name of the given plane to average in.

• turns (int) -- number of turns in the provided data.

Returns:

A numpy array with the averaged data for the given bpms.

turn_by_turn.utils.matrices_to_array(tbt_data: TbtData) → ndarray

Convert the matrices of a TbtData object to a numpy array.

Parameters:

tbt_data (TbtData) -- TbtData object to convert the data from.

Returns:

A numpy array with the matrices data.

turn_by_turn.utils.numpy_to_tbt(names: ~numpy.ndarray, matrix: ~numpy.ndarray, datatype: ~turn_by_turn.structures.TransverseData | ~turn_by_turn.structures.TrackingData = <class 'turn_by_turn.structures.TransverseData'>) → TbtData

Converts turn by turn matrices and names into a TbTData object.

Parameters:

• names (np.ndarray) -- Numpy array of BPM names.

• matrix (np.ndarray) -- 4D Numpy array [quantity, BPM, particle/bunch No., turn No.] quantities in order [x, y].

• datatype (DataType) -- The type of data to be converted to in the matrices. Either TransverseData (which implies reading X and Y fields) or TrackingData (which implies reading all 8 fields). Defaults to TransverseData.

Returns:

A TbtData object loaded with the matrices in the provided numpy arrays.