OMC3 Optics Analysis Workflow¶

This page contains a walk-through of a typical but simple analysis workflow with the omc3 package. To follow along, the reader needs to have installed the package and to have measurement or simulation data to use the codes on. In case the reader does not have appropriate data to follow along with, an old MAD-X script is provided below to create some.

The Analysis Workflow¶

A typical workflow with omc3 consists in performing analysis of measurement or simulation files, and eventually calculating corrections to apply. While omc3 provides python modules to handle the different aspects of these tasks, it also provides entrypoint scripts to be called from the commandline.

The first step in the workflow consists in a harmonic frequency analysis performed with the harpy module, while the second one is an optics analysis performed with the measure_optics module. The table below shows a general analysis workflow from BPM turn-by-turn measurements or simulation file to results, as well as the corresponding files at each step. Output files are written in the TFS format.

In this page, we will go through the essential steps in preparing and performing an analysis, by going from start to finish with a simple example. We will cover the use of the different entrypoints available to perform necessary steps.

Preparing Data for Analysis¶

Analysis in omc3 is mostly done from measurement data, but can also be done on simulated tracking data. While omc3 codes can read data from many machine formats, we will for demonstration purposes first convert our data to the LHC's SDDS binary format.

For this omc3 provides the tbt_converter entrypoint. A typical use consists in specifying the location of your turn-by-turn measurement files, the data type of said files and the location in which to write the converted SDDS data. All formats handled by our turn-by-turn package are supported.

For our example, let us say that when setting up tracking we have asked MAD-X to output the data into a file called trackone (this is actually the default name). Using the converter to make a compatible SDDS file then goes as:

python -m omc3.tbt_converter \
    --files trackone \
    --tbt_datatype trackone \
    --drop_elements LHCB1MSIA.EXIT.B1_P_ \
    --outputdir .

The converter will create new files with the .sdds suffix appended to the original filename. In our case, a trackone.sdds file will be created.

Creating a Model¶

In order to perform the optics analysis, one needs a model of the given machine to compare to. For this, omc3 provides the model_creator entrypoint, which allows you to run a model simulation of the desired machine and output the needed files.

In our example, we would like to compare our data to the nominal model of the 2018 LHC. Using the script to create a nominal model of the 2018 LHCB1, with the machine configuration and opticsfile used in our example, goes as:

python -m omc3.model_creator \
    --accel lhc \
    --type nominal \
    --year 2018 \
    --beam 1 \
    --energy 6.5 \
    --nat_tunes 62.31 60.32 \
    --modifiers opticsfile.22 \
    --outputdir lhc_model

Some of these options belong to the model_creator itself, while others depend explicitly on the chosen machine, here the LHC. Refer to the model creator's API documentation for the list of options.

The model creation runs a MAD-X scenario and outputs the relevant twiss results to the desired directory. Running ls lhc_model/ yields:

b2_errors.tfs    error_deffs.txt       macros    twiss_elements.dat
b2_settings.madx job.create_model.madx twiss.dat

Frequency Analysis¶

Once measurement or simulation is in the appropriate format, the first step as seen in the table above consists in a harmonic analysis of the data. To do so, omc3 provides the hole_in_one entrypoint, which will perform frequency analysis of the data when provided with the --harpy flag.

The script provides options involved in both data cleaning and parameter tweaking for the harmonic analysis, which is useful when you have relevant information about your measurements. To use these, refer to the Harpy Kwargs section of the hole_in_one API documentation.

In our example we will leave most of these to their default values to keep the analysis simple, but ask from harpy to output all computed results. We will input lhc for the --tbt_datatype flag, but if you skipped the use of the tbt_converter you should input the type of your machine there. Running the frequency analysis then goes as:

python -m omc3.hole_in_one --harpy \
    --files trackone.sdds \
    --tbt_datatype lhc \
    --turns 0 1023 \
    --autotunes transverse \
    --to_write lin spectra full_spectra bpm_summary \
    --outputdir harpy_output

In the output directory, harpy will create TFS files with the results of the analysis for both good BPMs and identified bad BPMs. The filenames are determined by appending the appropriate suffixes to the entry files.

In the output files, various properties are given in column form for each observation point. Running ls harpy_output/ yields the following result:

trackone.sdds.ampsx      trackone.sdds.freqsx
trackone.sdds.ampsy      trackone.sdds.freqsy
trackone.sdds.bad_bpms_x trackone.sdds.linx
trackone.sdds.bad_bpms_y trackone.sdds.liny

import tfs
import matplotlib.pyplot as plt

ampsx = tfs.read("harpy_output/trackone.sdds.ampsx")
freqsx = tfs.read("harpy_output/trackone.sdds.freqsx")

for bpm in ampsx.columns:
    if bpm in freqsx.columns:  # safety check but no reason it wouldn't be there
        plt.plot(freqsx[bpm], ampsx[bpm], ".-")
        # plt.stem(freqsx[bpm], ampsx[bpm])  # would be more accurate but might stress your system!

plt.setp(plt.gca(), xlabel=r"$Q_x$", ylabel="Amplitude", title="Horizontal Spectrum", xlim=(0, 0.5))
plt.show()

Optics Analysis¶

Once harmonic analysis has been performed, one can move on to the reconstruction of optics quantities from computed spectra and phases. To do so, omc3 provides the hole_in_one entrypoint, to be used this time with the --optics flag.

In our example we will ask to use the three_bpm_method when reconstructing beta functions from phase advances, as the default n_bpm_method (which is more accurate) requires providing a systematic errors definition file which our simulation does not provide (see the analytical n-bpm paper). Calling the entrypoint to perform optics analysis goes as:

python -m omc3.hole_in_one --optics \
    --accel lhc \
    --year 2018 \
    --beam 1 \
    --energy 6.5 \
    --files harpy_output/trackone.sdds \
    --model_dir lhc_model \
    --compensation none \
    --three_bpm_method \
    --outputdir measured_optics

Like other entrypoints, the optics analysis provides many options on methods to use and quantities to compute. To use these, refer to the Optics Kwargs section of the hole_in_one API documentation.

In the output files, various properties are given in column form for each observation point. Running ls measured_optics/ yields the following result:

beta_amplitude_x.tfs      kick_x.tfs           phase_y.tfs
beta_amplitude_y.tfs      kick_y.tfs           special_phase_x.tfs
beta_phase_x.tfs          measure_optics.log   special_phase_y.tfs
beta_phase_y.tfs          orbit_x.tfs          total_phase_x.tfs
interaction_point_x.tfs   orbit_y.tfs          total_phase_y.tfs
interaction_point_y.tfs   phase_x.tfs

python -m omc3.hole_in_one --harpy --optics \
    --files trackone.sdds \
    --tbt_datatype lhc \
    --turns 0 1023 \
    --autotunes transverse \
    --to_write lin spectra full_spectra bpm_summary \
    --accel lhc \
    --year 2018 \
    --beam 1 \
    --model_dir lhc_model \
    --compensation none \
    --three_bpm_method \
    --coupling_method 1 \
    --outputdir measured_optics

Amplitude Detuning Analysis¶

From the optics output files, in particular the kick_[xy].tfs files, one can perform amplitude detuning analysis. The detailed steps to run this from the GUI are described in the amplitude detuning analysis procedure.

Determining Corrections¶

From the results of an optics analysis, it is possible with omc3 to compute corrections in order to try and bring chosen parameters closer to the model values. However, due to the complexity of this workflow we will not provide a CLI walkthrough, and instead direct the user to use this functionality through the dedicated GUI.