turn_by_turn 1.5.0

Read and write turn-by-turn measurement files from different particle accelerator formats.

Turn-By-Turn

This package provides reading functionality for turn-by-turn BPM measurements data from different particle accelerators. It also provides writing functionality in the LHC's own SDDS format, through our sdds package. Supported accelerators include: LHC, SPS, PSB, IOTA, SuperKEKB, and others. PSB support is currently read-only and may change during LS3. Files are read into a custom-made TbtData dataclass encompassing the relevant information.

See the API documentation for details.

Installing

Installation is easily done via pip:

python -m pip install turn_by_turn

One can also install in a conda environment via the conda-forge channel with:

conda install -c conda-forge turn_by_turn

Example Usage

The package is imported as turn_by_turn, and exports top-level functions for reading and writing:

import turn_by_turn as tbt

# Loading a file is simple and returns a custom dataclass named TbtData
data: tbt.TbtData = tbt.read("Beam2@BunchTurn@2018_12_02@20_08_49_739.sdds", datatype="lhc")

# Easily access relevant information from the loaded data: transverse data,
# number of turns, bunches and IDs of the recorded bunches
first_bunch_transverse_positions: tbt.TransverseData = data.matrices[0]

# Transverse positions are recorded as pandas DataFrames
first_bunch_x = first_bunch_transverse_positions.X.copy()
first_bunch_y = first_bunch_transverse_positions.Y.copy()

# Do any operations with these as you usually do with pandas
first_bunch_mean_x = first_bunch_x.mean()

# Average over all bunches/particles at all used BPMs from the measurement
averaged_tbt: tbt.TbtData = tbt.utils.generate_average_tbtdata(data)

# Writing out to disk (in the LHC's SDDS format) is simple too, potentially with added noise
tbt.write("path_to_output.sdds", averaged_tbt, noise=1e-5)

License

This project is licensed under the MIT License - see the LICENSE file for details.