diff --git a/docs/assets/images/analysis_panel_cleaning.png b/docs/assets/images/analysis_panel_cleaning.png deleted file mode 100644 index f3d79c7c..00000000 Binary files a/docs/assets/images/analysis_panel_cleaning.png and /dev/null differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel.png b/docs/assets/images/betabeat_gui/analysis_panel.png new file mode 100644 index 00000000..c87dfc8f Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_frequency.png b/docs/assets/images/betabeat_gui/analysis_panel_frequency.png new file mode 100644 index 00000000..1ed93852 Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_frequency.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_frequency_controls_chart_options.png b/docs/assets/images/betabeat_gui/analysis_panel_frequency_controls_chart_options.png new file mode 100644 index 00000000..48055d2a Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_frequency_controls_chart_options.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_frequency_controls_nattune.png b/docs/assets/images/betabeat_gui/analysis_panel_frequency_controls_nattune.png new file mode 100644 index 00000000..0de81d86 Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_frequency_controls_nattune.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_frequency_controls_resonance_lines.png b/docs/assets/images/betabeat_gui/analysis_panel_frequency_controls_resonance_lines.png new file mode 100644 index 00000000..1f22164b Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_frequency_controls_resonance_lines.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_frequency_export.png b/docs/assets/images/betabeat_gui/analysis_panel_frequency_export.png new file mode 100644 index 00000000..05985383 Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_frequency_export.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_frequency_m1Qx_p2Qy_line.png b/docs/assets/images/betabeat_gui/analysis_panel_frequency_m1Qx_p2Qy_line.png new file mode 100644 index 00000000..df0103dc Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_frequency_m1Qx_p2Qy_line.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_frequency_manual_line.png b/docs/assets/images/betabeat_gui/analysis_panel_frequency_manual_line.png new file mode 100644 index 00000000..8798135a Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_frequency_manual_line.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_frequency_manual_line_show.png b/docs/assets/images/betabeat_gui/analysis_panel_frequency_manual_line_show.png new file mode 100644 index 00000000..16d23c7e Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_frequency_manual_line_show.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_frequency_nattune.png b/docs/assets/images/betabeat_gui/analysis_panel_frequency_nattune.png new file mode 100644 index 00000000..f056832f Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_frequency_nattune.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_table.png b/docs/assets/images/betabeat_gui/analysis_panel_table.png index ca84f046..cfb278ea 100644 Binary files a/docs/assets/images/betabeat_gui/analysis_panel_table.png and b/docs/assets/images/betabeat_gui/analysis_panel_table.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_time_space.png b/docs/assets/images/betabeat_gui/analysis_panel_time_space.png new file mode 100644 index 00000000..e648d408 Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_time_space.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_time_space_clean.png b/docs/assets/images/betabeat_gui/analysis_panel_time_space_clean.png new file mode 100644 index 00000000..15749442 Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_time_space_clean.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_time_space_manual_clean_after.png b/docs/assets/images/betabeat_gui/analysis_panel_time_space_manual_clean_after.png new file mode 100644 index 00000000..807c2634 Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_time_space_manual_clean_after.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_panel_time_space_manual_clean_before.png b/docs/assets/images/betabeat_gui/analysis_panel_time_space_manual_clean_before.png new file mode 100644 index 00000000..7a9ee8e6 Binary files /dev/null and b/docs/assets/images/betabeat_gui/analysis_panel_time_space_manual_clean_before.png differ diff --git a/docs/assets/images/betabeat_gui/analysis_spectrum.png b/docs/assets/images/betabeat_gui/analysis_spectrum.png deleted file mode 100644 index 1ff8b346..00000000 Binary files a/docs/assets/images/betabeat_gui/analysis_spectrum.png and /dev/null differ diff --git a/docs/assets/images/betabeat_gui/analysis_timespace.png b/docs/assets/images/betabeat_gui/analysis_timespace.png deleted file mode 100644 index c31b046d..00000000 Binary files a/docs/assets/images/betabeat_gui/analysis_timespace.png and /dev/null differ diff --git a/docs/assets/images/betabeat_gui/do_optics_dialog.png b/docs/assets/images/betabeat_gui/do_optics_dialog.png new file mode 100644 index 00000000..78d2fdab Binary files /dev/null and b/docs/assets/images/betabeat_gui/do_optics_dialog.png differ diff --git a/docs/assets/images/betabeat_gui/do_optics_dialog_settings.png b/docs/assets/images/betabeat_gui/do_optics_dialog_settings.png new file mode 100644 index 00000000..68c60fc8 Binary files /dev/null and b/docs/assets/images/betabeat_gui/do_optics_dialog_settings.png differ diff --git a/docs/assets/images/cleaning_settings.png b/docs/assets/images/cleaning_settings.png deleted file mode 100644 index 2c388a2f..00000000 Binary files a/docs/assets/images/cleaning_settings.png and /dev/null differ diff --git a/docs/guis/betabeat/analysis_panel.md b/docs/guis/betabeat/analysis_panel.md index 0d073564..cfd1c45b 100644 --- a/docs/guis/betabeat/analysis_panel.md +++ b/docs/guis/betabeat/analysis_panel.md @@ -1,67 +1,425 @@ -# The Beta-Beat GUI Analysis Panel +# The Analysis Panel -The analysis panel provides graphical interface to visualize results from harmonic analysis performed on measured data. -The results are given in the [`tfs`](https://pylhc.github.io/tfs/tfsformat.html){target=_blank} format. +The analysis panel provides graphical interface to visualize results from harmonic analysis performed on the given data. -In the analysis panel one can edit the `dp/p` value in the corresponding column, and see the changes applied. +
+
+ The Analysis Panel +
The Analysis Panel.
+
+
-## The Time / Space Tab +## Loading Files + +When the `harpy` analysis is started from the [BPM-Panel](bpm_panel.md), the results are automatically loaded when the analysis task has finished. +The buttons at the top of the panel provide functionality to manually load files and remove entries from the analysis table, +as well as to start the [optics analysis](#do-optics-dialog). + +- ++"Open Files"++{.green-gui-button}: Opens a dialog to select files to be loaded. The files will be **copied** into the `Measurements` folder and opened from there. +- ++"Attach Files"++{.yellow-gui-button}: Opens a dialog to select files to be loaded. The files will be **opened from their current location**. +- ++"Delete Files"++{.red-gui-button}: Removes the selected files from the analysis table. + A dialog will pop up, asking if the files should only be removed from this table, i.e. from being loaded in memory (see admonition below), or if they should also be deleted from disk.
+ :fontawesome-solid-triangle-exclamation:{.warning-colored} Due to [an unresolved issue][issue268]{target=_blank} it is currently **not advised** to delete files from disk. +- ++"Get Optics"++{.green-gui-button}: Opens [the optics analysis dialog](#do-optics-dialog) which can trigger an external python script to compute the optics functions from the harmonic analysis data of the selected files. + +
+
+ Table of loaded files. +
The table of currently loaded files.
+
+
+ +!!! warning "Memory Usage" + Files that are opened in this panel are stored in memory. + If your computer is running low on memory, you might want to close some of the open files. -In the `Time / Space` tab one can examine the phases and amplitudes, and can clean the values if needed (only `TUNEX` and `TUNEY` or `NATTUNEX` and `NATTUNEY`). +## The Time / Space Tab -If some values are obviously not inside a given bound, the 2 marker lines (see screenshot below) can be used to set the boundaries and to remove all data outside those boundaries. -The GUI will check if the removal is inside some predefined bounds to prevent accidental removal of too much data. +In the `Time / Space` tab one can examine the phases and amplitudes of different spectral lines over the length of the accelerator (per BPM), and perform cleaning procedures if needed. -!!! todo - Include a screenshot of the time / space panel with relevant info highlighted (see twiki) +
+
+ Time and Space tab. +
The Time / Space tab.
+
+
-### Cleaning of harmonic analysis output data +In the lists on the left-hand side, one can select from the resulting values of the [`harpy` analysis]. +These correspond to the columns in the `.lin[xy]` files and are separated by plane. +These include phase (`PHASE`), frequency (`FREQ`) and amplitude (`AMP`) of the lines identified by `harpy` as well as their respective errors (`ERR`). +The lines are multiples of the found tunes (`TUNE`) and can be identified by the two numbers in their name, +which correspond to the multiples of the horizontal and vertical tune, respectively, using underscores to represent a minus sign; +e.g. `PHASE1_2`, as seen in the screenshot above, corresponds to the phase of the line at frequency `Qx - 2Qy`. +In addtion, further data from the harmonic analysis is available, such as: -The harmonic analysis data used to obtain the optics functions can be cleaned using [Isolation Forest algorithm][sklearn_IF]. -It should prevent the appearance of unphysical spikes in the optics functions which are caused by the faulty BPMs remaining in the data after the TbT-data cleaning. +- `TUNE`: (driven) tune +- `NATTUNE`: natural tune (if available) +- `MU`: phase advance +- `CO`: closed orbit +- `BPM_RES`: BPM resolution +- `PK2PK`: peak-to-peak oscillation value +- `NOISE`: estimated cleaned noise -Isolation Forest perfroms anomaly detection on the whole set of selected measurements data. -Clicking on "Detect and remove bad BPMs"-button triggers an external python script which analyses the selected files. -The output file is written in the TFS format and contains the list of detected bad BPMs is written to the folder of the first selected measurement in the analysis table. +It is possible to select multiple files (++ctrl++ / ++shift++) at once, to compare the same quantities between measurements, and also multiple entries, e.g. to compare the amplitudes of different lines. -The output can be found in: `Measurements/.../bad_bpms_iforest_{x,y}`. +!!! tip "Deselection" + To see the data of one plane only, one can deselect the other plane by either chosing `None` at the bottom of the list + or by right-clicking into the respective list. -During IF-cleaning, the lines corresponding to detected faulty BPMs will be removed from the lin-files. -Cleaning can be reverted (the original lin files will be restored) by clicking Revert. +### Cleaning -After cleaning is finished, the optics function can be computed from the harmonic analysis data by clicking Get optics. +Even though extensive cleaning is done automatically in the [harmonic analysis][harpy_analysis], there can still be outliers in the data, +e.g. due to undetected [faulty BPMs][bad_bpms]. +To prevent the appearance of unphysical spikes in the optics functions, manual cleaning can be performed using the controls at the bottom left of the `Time / Space` tab, +which trigger the python [`linfile_clean` script][omc3_linfile_clean]{target=_blank}.
- Cleaning before optics analysis -
Cleaning before optics analysis
+ Cleaning before optics analysis +
Cleaning controls to clean data before optics analysis
-### Additional cleaning based on the tune +!!! tip "Keep BPMs" + Some BPMs, e.g. the AC-Dipole BPMs, are required for the optics analysis and **the analysis will fail** if they are not found in the data. + You can therefore specify to **keep these BPMs** in the [GUI Cleaning section of the Cleaning Settings Tab](settings.md#gui-cleaning) and they will be kept, + even if they are outside the given [cut-offs](#clean) or identified as [outliers](#auto-clean). + +!!! tip "Always remove BPMs" + If BPMs show up regularly as outliers in the data, independent of machine configuration, it is likely that they are [faulty BPMs][bad_bpms]. + You can specify to **always clean these BPMs** during the cleaning of the data in the `harpy` analysis via the `Bad BPMs` field in the [Cleaning Settings Tab](settings.md#cleaning-tab). + +#### Clean + +=== "Before Cleaning" + +
+
+ Natural Tune before cleaning. +
Identified natural tunes per BPM with outliers.
+
+
+ +=== "After Cleaning" + +
+
+ Natural Tune after cleaning. +
Identified natural tunes per BPM after cleaning outliers.
+
+
+ +This section allows for the most manual cleaning of the data by setting the cursors (lines) around the data to keep. +This can be done manually by dragging their markers on the right-hand-side of the chart. +They can also be set automatically at the position corresponding to the _Sigmas_, +i.e. the number of standard deviations away from the mean **of all data currently shown in the chart**, +by using the ++"Set Cursors"++ button. +Then press ++"Clean"++{.red-gui-button} to remove the data outside of the selected area, as shown in the images above. + +!!! info "Automatic Data Selection" + The order of the cursors does not matter, and neither does the selection of data: The GUI will automatically determine the area between the cursors and check + which of the selected data sources, columns and/or files, has most (default: more than 70% of the data; see the warning admonition below) of its data in that area. -Additionally, BPMs can be cleaned based on the tune values computed by harmonic analysis. The chart displaying the selected columns of harmonic analysis data has interactive cursors. These cursors can be moved manually to set the thresholds for tune-based cleaning - all BPMs having tune values outside of the set range will be removed. The cursors can be also automatically set to e.g. 4 sigmas deviation from the average tune values over all BPMs. +!!! warning "Default Bounds" + Before cleaning, the GUI will check if the ratio of remaining data-points is inside predefined bounds (default: `0.7`, i.e. keep at least 70%) to **prevent accidental removal of too much data**. + This ratio, as well as the GUI-default value for the `sigmas` and `limit` parameter can be changed [through the `bbgui_user.properties` file][additional_defaults]. -### Summary of cleaning steps before optics analysis +#### Auto Clean -- [ ] Before loading tbt-files: check SVD settings and signal cuts in the global settings panel -- [ ] After harmonic analysis: Detect bad BPMs with Isolation Forest -- [ ] If neccessary: check tunes in the chart, set cursors, clean tune outliers. +A more automated cleaning approach can be utilized with the help of the _outlier filter_ +(see Section 3.2.3 in [Malina2018][malina2018] +or Section II.E.1 in [Dilly2023][dilly2023]), which iteratively removes points in the tails of the data until the distribution of the remaining data is close to a normal distribution. +The _limit_ parameter defines a "save zone" in standard deviations around the mean, in which data will not be removed (default: `0.0`, i.e. any datapoint could be removed). +This cleaning can be run by simply pressing the ++"Auto"++{.red-gui-button} button and is then applied to **all data currently shown in the chart**, individually per column, plane and `sdds`-file. + +#### Undo Cleaning + +The [`linfile_clean`][omc3_linfile_clean]{target=_blank} function automatically creates a backup of the data before cleaning, +which can be restored by pressing the buttons in this section. +Use ++"X"++ to restore the latest backup for the X-plane and ++"Y"++ for the Y-plane, + or press ++"Both"++ to restore the latest backup for both planes. + +!!! warning "Backup History" + At each cleaning run a **separate backup per file** will be created. + The undo-functionality always restores the latest backup file found and then deletes it. + You can therefore undo multiple cleaning steps by pressing the buttons multiple times. + The latest backup is chosen **per `lin`-file** independently, i.e. you can go back to different states for the X and Y planes, + but **not for different columns** if you have cleaned them in the same step, as they are in the same file. + Conversely, if you cleaned another column than the currently visible one in the same file, **restoring the backup might restore the wrong column**. + If no backup was found, a warning will be logged in the [console](common_components.md#console). ## The Frequency Tab -The `Frequency` tab displays the computed frequencies for every BPM. +
+
+ Frequency tab. +
The Frequency tab.
+
+
+ +The `Frequency` tab displays the computed spectrum for every BPM. +Here, one can visually check the quality of the data, identify resonance lines, and perform some additional (natural-) tune windowing. + +It is possible to select multiple files (++ctrl++ / ++shift++) as well as multiple BPMs (++ctrl++ / ++shift++) at once to compare the frequency data between them. +Depending on the number of selected files and BPMs as well as the frequency resolution of the spectra, the GUI may take a few seconds to display all data. + +!!! tip "Deselection" + To see the frequency data of one plane only, one can deselect the other plane by either chosing `None` at the bottom of the list of BPMs + or by right-clicking into the respective list. + +!!! tip "Find BPMs" + The BPMs in the list are sorted alphabetically. + Use the text field and the ++"Find BPM"++ button to quickly find BPMs in the list and **automatically select them**. + The text input is based on regular expressions and **all BPMs that match the pattern** in both planes will be selected. + Note that `^.*` and `.*$` will be added automatically to start and end of the string respectively, + to look for your pattern **anywhere** in the BPM name. + +Use the controls at the bottom left of the panel for the additional functionality, which is described below. + +### Resonance Lines + +
+
+ Frequency tab resonance lines controls. +
Resonance lines controls at the bottom of the Frequency tab.
+
+
+ +Activate these controls to mark the location of resonance lines in the spectrum with dashed vertical lines and bars. +Choose from the dropdown menu which tune values should be used for the calculation of the lines: + +- **Nat. Tune (Model)**: The natural tune set in the currently loaded model. +- **ACD Tune (Model)**: The ac-dipole tune set in the currently loaded model _(if available)_. +- **ADT Tune (Model)**: The adt-tune set in the currently loaded model _(if available)_. +- **Nat. Tune (Measured)**: The average natural tune of all measured BPMs. +- **Driven Tune (Measured)**: The average driven tune of all measured BPMs. +- **Nat. Tune (Gui)**: The currently set natural tune in the [tunes settings](settings.md#tunes-tab) _(usually same as model)_. +- **Driven Tune (Gui)**: The currently set driven tune in the [tunes settings](settings.md#tunes-tab) _(usually same as model)_. + +The range of orders of the resonance lines to be shown can be chosen by changing the values in the text fields, +where the order `n` is defined as the sum of absolute multiples of the horizontal and vertical tune of the line, e.g. the order of the `2Qy - Qx` line is `n = 2 + 1 = 3`. +Different orders will be shown in different colors. +Hovering the resonance line towards the top of the chart will show a tooltip with the tune multiples of that line and its frequency. + +Clicking the ++"Custom"++ button will open a dialog to manually enter frequency and labels of additional vertical bars to be shown in red in the chart. + +
+
+Custom lines dialog. +
The custom lines dialog to manually add lines.
+
+
+ +Use ++"Add Line"++{.green-gui-button} to add a new line based on your input to the table and ++"Remove"++{.red-gui-button} to remove the currently selected line. +The lines in the charts will only update after clicking ++"Approve"++. + +=== "Natural Tune Line" + +
+
+ Natural tune line. +
The spectrum showing a tooltip at the natural tune line.
+
+
+ +=== "2Qy - Qx Line" + +
+
+ 2Qy - Qx line. +
The spectrum showing a tooltip at the 2Qy - Qx line.
+
+
+ +=== "Manual Line" + +
+
+ Manual line. +
The spectrum showing a tooltip at a manually added marker at 0.265.
+
+
+ +### Natural Tune Window + +The natural tune window controls help to correctly identify the natural tune in the spectrum and assign it to the `NATTUNE`-column in the lin-file +using the [`update_nattune_in_linfile` script][omc3_update_nattune]{target=_blank}. +This avoids having to re-run the `harpy` analysis with different tolerance windows and natural tunes settings. +Accurate identification of the natural tune is important e.g. for [amplitude detuning analysis][amplitude_detuning_analysis]. + +There are two main reasons for a possible misidentification of the natural tune line in the spectrum by the `harpy` analysis, +even when the values are set "correctly" (in accordance with the model) in the [`Tune Settings`](settings.md#tunes-tab): + +- Due to detuning, the natural tune line can be shifted and might not be any longer within the tolerance window. +This can in particular happen during a wide range of amplitude detuning scans, for which one does not want to change the tolerance window at every kick, +or cannot easily make it larger as it would include the driven tune line. +- Large resonances can appear within the tolerance window, e.g. excited by the approach of the natural tune due to detuning effects, +and might be misidentified as the natural tune line when their amplitude is higher than that of the natural tune line itself. + +
+
+ Frequency tab natural tune window controls. +
Natural tune window controls at the bottom of the Frequency tab.
+
+
+ +To update the natural tune in the lin-file, first activate the vertical cursors at the top of the chart by setting a tick in the **Show** checkbox, +they will appear at their last set position or at 0 if they have not been set yet. + +!!! tip "Cursors for each plane" + If BPMs from both planes are selected, two sets of cursors will appear: blue for the horizonal spectrum and red for the vertical spectrum. + In case only one plane is selected, only one set of cursors will appear. + To update the amount of cursors shown, select BPMs in the desired planes, then untick and re-activate the **Show** checkbox. + +Click ++"Set Window"++ to set the markers around the model natural tune with a spacing given by the _Tolerance_, +both of which are taken from the [`Tune Settings`](settings.md#tunes-tab). + +
+
+Natural tune line. +
The spectrum showing a tooltip at the natural tune line.
+
+
+ +Adapt the cursors such that the natural tune line is the highest line between them, +avoiding resonances and the driven tune line. +For measurements with many BPMs not showing a clear natural tune line, tightening the window can also help reducing the errorbar on the tune. + +!!! tip "Identifying the Natural Tune" + If unsure which of the shown lines is the natural tune, it often helps to look at the spectrum of other kicks, + e.g. the ones with similar kick-amplitude in an amplitude detuning scan. + The natural tune line in this measurement is usually the line closest to the natural tune in the other measurements, + as the detuning effect is usually very small between similar kick amplitudes. + +A ticked _"All BPMs"_ checkbox will update the `NATTUNE`-column for all BPMs, while an unticked one will only update the currently selected BPMs. +If unticked and no BPMs are selected in a given plane that plane will be skipped, +but if _"All BPMs"_ is active, both planes will be updated as long as a window is set for each (see tip above). +If there is no window set for a plane, it will be skipped. + +Click ++"Update Lin-Files"++{.green-gui-button} to update the `NATTUNE`-column in the lin-files of the currently selected measurements, with the window defined by the currently set cursors. + +!!! tip "The `Empty` dropdown" + In rare cases, e.g. when using a large frequency spacing (low number of [output bits](settings.md#harpy-tab)) or a very small tolerance window, + it can happen that for some BPMs no frequency line lies between the cursors. + In this case, the action taken in the `Empty` dropdown menu is applied: + + - **error** _(default)_: The `NATTUNE`-column is not updated and an error is raised. + - **ignore**: The BPM is ignored and the value in the `NATTUNE`-column is not updated. + - **remove**: The BPM is removed from the lin-file. + +!!! bug "Free Kicks" + Do **NOT** use the Natural Tune Updater when working with free kicks, as the script will add a `NATTUNE`-Column to the lin-file! + +### Chart Options + +
+
+ Frequency tab chart controls. +
Chart options controls at the bottom of the Frequency tab.
+
+
+ +Use the first drop-down in the chart options to select the display type of the chart: + +- **Stem** _(default)_: +This shows the spectrum in a stem plot, i.e. as thin vertical lines for each measured frequency, starting at the bottom of the chart and ending in a marker at the amplitude value. +- **Bars**: +This also shows the spectrum in a stem-like plot, but with wider stems and no markers at the top. +This was the default in GUI versions pre 2019 and comes with a warning: When plotting multiple files/BPMs the bars are "stacked" **next** to each other, +which makes it hard to see which frequency they actually belong to. +- **Points**: +This shows the spectrum in a scatter plot, i.e. as markers for each frequency set at the corresponding amplitude. +These are the markers of the _Stems_ plot, but without the actual stems. +- **Lines**: +This shows the spectrum in a scatter plot, i.e. as markers for each frequency set at the corresponding amplitude connected by lines. +So this is the same as _Points_ but with additional lines between the markers. + +Two methods are available to save the chart to file: + +- ++"GUI"++ : +This button will open a dialog asking where to save the **chart component directly from java** as a **PNG file**. +The output will look exactly like the chart in the GUI, as it is rendered directly from `java`. +- ++"PDF"++ : +This button allows passing the currently selected data to the [`plot_spectrum` script][omc3_plot_spectrum]{target=_blank} to save the spectrum as a **PDF file**. +As the spectrum is completely rendered by the `python` script, the output will look different from the chart in the GUI but will show in general the same information, with some important caveats listed below. + + - Clicking the button will open a dialog to select an output **directory**. + As multiple files might be created, the filenames are determined automatically. + Subsequently, a second dialog will appear, displaying the selected path (modifiable if required). + In this window, the data to be grouped within the same plots/files can be defined: + +
+
+ Export Spectrum Dialog. +
The export spectrum dialog.
+
+
+ + - In any case, the spectrum of horizontal and vertical BPMs will be split into separate plots on the top and bottom of the same file. + Which also means, that no matter in which plane you have selected a BPM - if it has a horizontal and a vertical spectrum they will both be plotted. + - _"Combine Plots by BPMs"_: Will plot all selected BPMs into the same plots in the same file, with the BPM name in the legend. + If deactivated, there will be separate files per BPM with the BPM name in the filename. + - _"Combine Plots by Measurements"_: Will plot all selected Measurements into the same plots in the same file, with the Measurement name in the legend. + If deactivated, there will be separate files per Measurement with the Measurement name in the filename. + - Having both _"BPMs"_ and _"Measurements"_ activated will therefore lead to a single output file, with a chart for each plane and a combination of BPM and Measurement names as legend. + - Having both _"BPMs"_ and _"Measurements"_ deactivated will lead to `N = No. of selected BPMs x No. of selected Measurements` files, containing two charts for the planes with each showing only a single spectrum. + Both, BPM and Measurement name will be in the filename. + +## Do Optics Dialog + +The ++"Get Optics"++{.green-gui-button} button opens a dialog to select the settings and run the [optics analysis][optics_analysis], +which will calculate the optics parameters based on the spectra of the [currently selected files](#loading-files). + +=== "Closed Settings" + +
+
+ The 'Do Optics' Dialog +
The "Do Optics" Dialog.
+
+
+ +=== "Open Settings" + +
+
+ The 'Do Optics' Dialog with open settings +
The "Do Optics" Dialog with open settings.
+
+
+ +It is possible to combine all selected files into a single optics analysis, using the individual measurements for statistics. +In this case **a descriptive output name** should be specified for the analysis, the prefix of which will already be provided as a suggestion. +When unchecking the _Combine Analysis_ option, each open file will produce an optics analysis named based on the name of the `harpy` output files, as displayed in the table at the top of this panel. +All optics analysis results are stored in the `Results` folder, and will be automatically loaded into the [Optics Panel](optics_panel.md). + +### Settings -A `Get Optics` button can be used to start the optics calculation. -This will call an external python script again, with the results available in the [Optics Panel](optics_panel.md). +By expanding the _Settings_ section at the bottom of the dialog +one can change the [settings](settings.md) of the _[Optics tab](settings.md#optics-tab)_. -### Nattune Updater +!!! warning "Changing the Settings" + This will **change the global settings** for all subsequent analysis runs, + not just for the current one! + You need to click the ++"Apply"++ button to actually apply these settings before the run. -- You can set a frequency range and it does not redo the analysis but just picks the highest peak in that range and assigns it to `NATTUNE` in the lin-file. -- This should be very helpful for amplitude detuning analysis. -- Do NOT use the Nattune-Updater if you have free kicks (it adds a `NATTUNE`-Column to the lin-file). +[additional_defaults]: defaults.md#additional-gui-defaults +[harpy_analysis]: ../../measurements/physics/harpy.md +[bad_bpms]: ../../measurements/physics/bpm_filtering.md +[amplitude_detuning_analysis]: ../../measurements/procedures/ampdet.md +[optics_analysis]: ../../measurements/physics/optics.md -!!! todo - Include a screenshot of the frequency panel. +[omc3_linfile_clean]: https://pylhc.github.io/omc3/entrypoints/scripts.html#linfile-cleaning +[omc3_update_nattune]: https://pylhc.github.io/omc3/entrypoints/scripts.html#update-natural-tune-in-lin-files +[omc3_plot_spectrum]: https://pylhc.github.io/omc3/entrypoints/plotting.html#plot-spectrum +[malina2018]: https://repository.cern/records/bxyez-pt407 +[dilly2023]: http://cds.cern.ch/record/2883681/ +[issue268]: https://gitlab.cern.ch/acc-co/lhc/lhc-app-beta-beating/-/issues/268 - [sklearn_IF]: https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.IsolationForest.html +*[LHC]: Large Hadron Collider +*[SPS]: Super Proton Synchrotron +*[PS]: Proton Synchrotron +*[PSB]: Proton Synchrotron Booster +*[OMC]: Optics Measurement and Correction +*[BPM]: Beam Position Monitor +*[BPMs]: Beam Position Monitors diff --git a/docs/guis/betabeat/bpm_panel.md b/docs/guis/betabeat/bpm_panel.md index 605088c1..c270d979 100644 --- a/docs/guis/betabeat/bpm_panel.md +++ b/docs/guis/betabeat/bpm_panel.md @@ -16,7 +16,7 @@ and select the data to be analyzed further. !!! warning "Not yet implemented" The GUI does [not yet support loading of measurement groups][issue282]{target=_blank .cern_login} (i.e. kick groups). - The idea is to load all data from a single [kick-group, as defined in the Multiturn GUI](../multiturn/excitation.html#kick-groups) at once + The idea is to load all data from a single [kick-group, as defined in the Multiturn GUI][kick_groups] at once or monitor a currently active kick-group and load the files as they are created. ### Open Files @@ -42,7 +42,7 @@ Use the ++"Open Files"++{.green-gui-button} button to open turn-by-turn data. Multiple files can be opened at once and are added to the current `Measurements` directory, as well as to the table of loaded files in the panel. If the file contained multiple bunches, they are added as separate entries (see [below](#table-of-loaded-files)). -If the ["Analyse TbT files on opening" setting](settings.md#gui-tab) is active, a window will open to prompt the user with the ["Do analysis Dialog"][do_analysis_dialog]. +If the ["Analyse TbT files on opening" setting](settings.md#gui-tab) is active, a window will open to prompt the user with the ["Do analysis Dialog"](#do-analysis-dialog). !!! tip "Reopening Files" - If you are opening a file with the same filename as an already opened file, an error will be thrown. @@ -130,6 +130,13 @@ You can select multiple measurements at once to compare them, but only one BPM p +!!! tip "Find BPMs" + The BPMs in the list are sorted by longitudinal position in model loaded when the file was opened. + Use the text field and the ++"Find BPM"++ button to quickly find BPMs in the list and **automatically select them**. + The text input is based on regular expressions and **the first BPM matching the pattern** will be selected. + Note that `^.*` and `.*$` will be added automatically to start and end of the string respectively, + to look for your pattern **anywhere** in the BPM name. + ### Bad BPMs After [harmonic-analysis](#start-analysis) has been performed, the [bad BPMs][bpm_filtering] will be marked in red in the lists. @@ -226,11 +233,12 @@ The _Suffix_-field will be automatically set from your suffix-choices in the [_H [issue283]: https://gitlab.cern.ch/acc-co/lhc/lhc-app-beta-beating/-/issues/283 [issue285]: https://gitlab.cern.ch/acc-co/lhc/lhc-app-beta-beating/-/issues/285 [bpm_filtering]: ../../measurements/physics/bpm_filtering.md -[do_analysis_dialog]: analysis_panel.md#do-analysis-dialog [harpy_analysis]: ../../measurements/physics/harpy.md +[kick_groups]: ../multiturn/excitation.md#kick-groups *[LHC]: Large Hadron Collider *[SPS]: Super Proton Synchrotron *[PS]: Proton Synchrotron *[PSB]: Proton Synchrotron Booster *[BPM]: Beam Position Monitor +*[BPMs]: Beam Position Monitors diff --git a/docs/guis/betabeat/correction_panel.md b/docs/guis/betabeat/correction_panel.md index 88e73c9f..15a5a058 100644 --- a/docs/guis/betabeat/correction_panel.md +++ b/docs/guis/betabeat/correction_panel.md @@ -4,7 +4,9 @@ The `Correction` panel displays the corrections computed from the `Optics` panel It provides an `Open Knob Panel` button to access the LHC beam process list. -## The Knob Panel +## Knob Creation + +### The Knob Panel Through the `Knob Panel`, corrections can be provided directly inside the LHC beam system. @@ -31,3 +33,5 @@ By selecting one, the user can examine or visualize the values attributed to eac !!! todo Include a screenshot of the Knob Panel view knobs chart + +## Correction Checks diff --git a/docs/guis/betabeat/settings.md b/docs/guis/betabeat/settings.md index 26e9841f..1824c459 100644 --- a/docs/guis/betabeat/settings.md +++ b/docs/guis/betabeat/settings.md @@ -12,7 +12,7 @@ The settings window can be initialized by the gear icon highlighted in red and can be reverted with the ++"Reset"++ button. @@ -70,7 +70,7 @@ This is in contrast to the other settings tabs, which control the settings passe - **Analyse TbT Files on Opening**: If active and you open a turn-by-turn file, via the ++"Open Files"++{.green-gui-button} in the [BPM Panel](bpm_panel.md), - `harpy` analysis will be automatically started (for now: the user will be prompted with the ["Do analysis Dialog"](bpm_panel.md#do-analysis) directly after TbT import). + `harpy` analysis will be automatically started (for now: the user will be prompted with the ["Do analysis Dialog"](bpm_panel.md#do-analysis-dialog) directly after TbT import). - **Python Path**: Change the location of the `python` executable to be used to run the python scripts. @@ -345,12 +345,12 @@ introduced by the AC-Dipole and if they are not found in the data, the optics an Files to to use for the optics analysis. These are the output files from `harpy`. This field is not editable and is only shown here, as `files` is an argument to `optics_measurement` and an attribute on the internal `OpticsSettings` class. - The actual files to use are chosen from the [Analysis Panel](analysis_panel.md), after which this field is automatically filled in when shown in the [Run Optics](analysis_panel.md#run-optics) popup window. + The actual files to use are chosen from the [Analysis Panel](analysis_panel.md), after which this field is automatically filled in when shown in the [Run Optics](analysis_panel.md#do-optics-dialog) popup window. - **Outputdir**: Directory to place to output of the optics analysis. The field is not editable and is only shown here, as `outputdir` is an argument to `optics_measurement` and an attribute on the internal `OpticsSettings` class. - The actual directory is chosen by the user per analysis, when setting an analysis name in the [Run Optics](analysis_panel.md#run-optics) popup window. + The actual directory is chosen by the user per analysis, when setting an analysis name in the [Run Optics](analysis_panel.md#do-optics-dialog) popup window. - **Calibrationdir**: Path to the directory containing the [calibration][bpm_calibration] files, used to rescale the BPM amplitudes and amplitude errors. diff --git a/docs/guis/usage/guidelines.md b/docs/guis/usage/guidelines.md index f91a16c7..f04f3c47 100644 --- a/docs/guis/usage/guidelines.md +++ b/docs/guis/usage/guidelines.md @@ -11,9 +11,9 @@ This is for three reasons: ### Model-View-Controller Architecture -While not strictly enforced, our GUIs follow the [Model-View-Controller][mvc_wiki]{target="_blank"} architecture, +While not strictly enforced, our GUIs follow the [Model-View-Controller][mvc_wiki]{target=_blank} architecture, as it is a very useful and therefore also very common GUI pattern. -[A better explanation can be found here][mvc_geeks]{target="_blank"}, but this section summarizes a few key points relevant to our usecase. +[A better explanation can be found here][mvc_geeks]{target=_blank}, but this section summarizes a few key points relevant to our usecase. The main philosophy of the MVC architecture is to separate the actual GUI elments, the _View_, from the underlying data, stored in the _Model_, and let the _Controller_ handle the communication between the two and with the user. @@ -35,7 +35,7 @@ this code has been used for many years and probably will be continued to be used **Try to keep it clean!** -Because GUI testing is hard and because we have easy access to old versions via [CAS][cas_cern]{target="_blank" .cern_internal}, +Because GUI testing is hard and because we have easy access to old versions via [CAS][cas_cern]{target=_blank .cern_internal}, there is no tests suite and no review process for the `java` development and changes can be simply pushed to the `master` branch. Some "best practices" have been established through the years: @@ -51,9 +51,9 @@ Some "best practices" have been established through the years: - Do not use `Strings` for file paths, for now we mostly use `File` objects (but see also the [Issue #239][issue_239]). !!! tip "Factory Pattern" - One pattern that you will find in different places of `java` code is the [factory design-pattern][factory_pattern_wiki]{target="_blank"}. + One pattern that you will find in different places of `java` code is the [factory design-pattern][factory_pattern_wiki]{target=_blank}. While useful in some scenarios, I personally (jdilly) find it too verbose and annoying to implement, - in the past there were even [scripts to automatically write the factory-code][internal_program_writer]{target="_blank"} because it needs so many lines of repeating code. + in the past there were even [scripts to automatically write the factory-code][internal_program_writer]{target=_blank} because it needs so many lines of repeating code. In particular, this pattern was used for the [creation of the `ExternalProgram` classes][factory_pattern_doc] to allow the setting of multiple attributes before even creating the class, without having to write multiple constructors diff --git a/docs/measurements/physics/optics.md b/docs/measurements/physics/optics.md new file mode 100644 index 00000000..f378a720 --- /dev/null +++ b/docs/measurements/physics/optics.md @@ -0,0 +1,35 @@ + +# Optics Analysis + +This page summarizes how the optics analysis is performed with the `measure_optics` module, from the physics point of view. +If you want to know how to **use** the `measure_optics` module through `hole_in_one`, refer to the [`omc3` analysis workflow][omc3_analysis]. + +!!! todo "Implement this page" + Explain how the analysis works. + If too long, maybe make sections their own page? + +## Linear Optics + +### Phase, Phase Advance and Special Phases + +### Beta from Phase + +### Beta from Amplitude + +### Action + +### Dispersion and Normalized Dispersion + +### Coupling + +See [Coupling](coupling.md) + +## Nonlinear Optics + +### Resonance Driving Terms + +### Combined Resonance Driving Terms + +### Chromatic Beating + +[omc3_analysis]: ../../packages/omc3/analysis.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 3dea5795..ddb79bc0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -209,6 +209,7 @@ nav: - BPM-Calibration: measurements/physics/bpm_calibration.md - BPM-Filtering: measurements/physics/bpm_filtering.md - Harmonic Analysis: measurements/physics/harpy.md + - Optics Analysis: measurements/physics/optics.md - Coupling: measurements/physics/coupling.md - K-Mod: measurements/physics/kmod.md - Linear IR Optics: measurements/physics/ir_linear_optics.md