Metadata-Version: 2.4
Name: turn_by_turn
Version: 1.5.0
Summary: Read and write turn-by-turn measurement files from different particle accelerator formats.
Project-URL: homepage, https://github.com/pylhc/turn_by_turn
Project-URL: repository, https://github.com/pylhc/turn_by_turn
Project-URL: documentation, https://pylhc.github.io/turn_by_turn/
Author-email: OMC Team <pylhc@github.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: h5py>=2.9
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.1
Requires-Dist: scipy>=1.5
Requires-Dist: sdds>=0.4
Provides-Extra: all
Requires-Dist: pytest-cov>=2.9; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'all'
Requires-Dist: sphinx>=7.0; extra == 'all'
Requires-Dist: tfs-pandas>=4.0.0; extra == 'all'
Requires-Dist: xsuite>=0.54.6; (sys_platform != 'win32') and extra == 'all'
Provides-Extra: doc
Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'doc'
Requires-Dist: sphinx>=7.0; extra == 'doc'
Provides-Extra: madng
Requires-Dist: tfs-pandas>=4.0.0; extra == 'madng'
Provides-Extra: test
Requires-Dist: pytest-cov>=2.9; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: tfs-pandas>=4.0.0; extra == 'test'
Requires-Dist: xsuite>=0.54.6; (sys_platform != 'win32') and extra == 'test'
Provides-Extra: xsuite
Requires-Dist: xsuite>=0.54.6; (sys_platform != 'win32') and extra == 'xsuite'
Description-Content-Type: text/markdown

# Turn-By-Turn

[![Cron Testing](https://github.com/pylhc/turn_by_turn/workflows/Cron%20Testing/badge.svg)](https://github.com/pylhc/turn_by_turn/actions?query=workflow%3A%22Cron+Testing%22)
[![Coverage](https://raw.githubusercontent.com/pylhc/turn_by_turn/python-coverage-comment-action-data/badge.svg)](https://github.com/pylhc/turn_by_turn/tree/python-coverage-comment-action-data)
[![PyPI Version](https://img.shields.io/pypi/v/turn_by_turn?label=PyPI&logo=pypi)](https://pypi.org/project/turn_by_turn/)
[![GitHub release](https://img.shields.io/github/v/release/pylhc/turn_by_turn?logo=github)](https://github.com/pylhc/turn_by_turn/)
[![Conda-forge Version](https://img.shields.io/conda/vn/conda-forge/turn_by_turn?color=orange&logo=anaconda)](https://anaconda.org/conda-forge/turn_by_turn)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5554916.svg)](https://doi.org/10.5281/zenodo.5554916)

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](https://pylhc.github.io/turn_by_turn/) for details.

## Installing

Installation is easily done via `pip`:

```bash
python -m pip install turn_by_turn
```

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

```bash
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:

```python
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](LICENSE) file for details.
