3

This is the python-tool package of the optics measurements and corrections team (OMC) at CERN.

Most of the codes are generic and not limited to CERN accelerators. You can use it easily for your favourite circular accelerator. To see how to adapt this for your accelerator, see our documentation, Model section. To contribute, see the Hints for Developers section below.

Documentation

• Autogenerated docs via Sphinx can be found at https://pylhc.github.io/omc3/.
• General documentation of the OMC-Teams software is located at https://twiki.cern.ch/twiki/bin/view/BEABP/OMC.

Getting Started

The omc3 package is Python 3.7+ compatible, but not yet deployed to PyPI. The best way to install is though pip and VCS:

git clone https://github.com/pylhc/omc3
pip install /path/to/omc3

Or simply from the online master branch, which is stable:

pip install git+https://github.com/pylhc/omc3.git

After installing, codes can be run with either python -m omc3.SCRIPT --FLAG ARGUMENT or calling path to the .py file directly.

Functionality

Main Scripts

Main scripts to be executed lie in the /omc3 directory. These include:

• hole_in_one.py to perform frequency analysis on turn by turn BPM data and infer optics (and more) for a given accelerator.
• madx_wrapper.py to start a MAD-X run with a file or string as input.
• model_creator.py to provide optics models required for optics analysis.
• run_kmod.py to analyse data from K-modulation and return the measured optics functions.
• tbt_converter.py to convert different turn by turn datatypes to sdds, and add noise.
• amplitude_detuning_analysis.py to perform amp. det. analysis on optics data with tune correction.

Plotting Scripts

Plotting scripts for analysis outputs can be found in /omc3/plotting:

• plot_spectrum.py to generate plots from files generated by frequency analysis.
• plot_bbq.py to generate plots from files generated by BBQ analysis.
• plot_amplitude_detuning.py to generate plots from files generated by amplitude detuning analysis.
• plot_optics_measurements.py to generate plots from files generated by optics_measurements.
• plot_tfs.py all purpose tfs-file plotter.

Other Scripts

Other general utility scripts are in /omc3/scripts:

• update_nattune_in_linfile.py to update the natural tune columns in the lin files by finding the highest peak in the spectrum in a given interval.
• write_madx_macros.py to generate MAD-X tracking macros with observation points from a twiss file.
• merge_kmod_results.py to merge lsa_results files created by kmod, and add the luminosity imbalance if the 4 needed IP/Beam files combination are present.

Example use for these scripts can be found in the tests files.

Quality checks

• Unit and accuracy tests are run automatically through CI Github Actions. See our workflows in this readme.
• Additional checks for code-complexity, design-rules, test-coverage and duplication are made through CodeClimate.
• Pull requests implementing functionality or fixes are merged into the master branch after passing CI, and a reviewer's approval.

Changelog

See the CHANGELOG file.

Related Packages

• tfs-pandas
• sdds-reader
• generic parser
• PyLHC
• Beta-Beat Source
• optics functions

Hints for Developers

In case you want to contribute to omc3's development, you should install it in editable mode:

git clone https://github.com/pylhc/omc3
pip install --editable omc3

You can install extra dependencies (as defined in setup.py) suited to your use case with the following commands:

pip install --editable omc3[test]
pip install --editable omc3[test,doc]
pip install --editable omc3[all]

Open an issue, make your changes in a branch and submit a pull request.

Authors

• pyLHC/OMC-Team - Working Group - pyLHC

License

This project is licensed under the GNU GPLv3 License. Please take a moment to check its permissivity - see the LICENSE file for details.