Merge branch 'user_guide_updates_bpm_panel' into user_guide_updates_bbgui_analysis_panel

Author: JoschD

docs/guis/betabeat/bpm_panel.md

@@ -184,7 +184,7 @@ Click the ++"Run"++ button to start the analysis.
 
 ### Harmonic Analysis
 
-Keeping the _Optics Analysis_ checkbox unchecked will only perform the harmonic analysis.
+Keeping the _Optics Analysis_ checkbox unchecked will only perform the [harmonic analysis][harpy_analysis].
 
 In this case, you will **not be able to specify an output name** for the results, as the resulting files will be **automatically** put into subfolders of the `Measurements` folder, based on the name of the `.sdds` files.
 They therefore usually appear within the same folder as the turn-by-turn data.
@@ -227,6 +227,7 @@ The _Suffix_-field will be automatically set from your suffix-choices in the [_H
 [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
 
 *[LHC]: Large Hadron Collider
 *[SPS]: Super Proton Synchrotron

docs/guis/betabeat/settings.md

@@ -156,7 +156,7 @@ The fields are non-editable when it does not make sense in the current settings
   </center>
 </figure>
 
-The Harpy tab contains the settings for the harmonic `harpy` analysis.
+The Harpy tab contains the settings for the [harmonic `harpy` analysis][harpy_analysis].
 
 - **Files**:
   This field is not editable and automatically set when selecting TbT files in the [BPM Panel](bpm_panel.md) and running the analysis.
@@ -244,7 +244,7 @@ The `python` default is `""`, i.e. no suffix.
   </center>
 </figure>
 
-Most of the cleaning, for which the settings can be changed here, are part of the harmonic analysis module `harpy` in `omc3`
+Most of the cleaning, for which the settings can be changed here, are part of the [harmonic analysis module `harpy` in `omc3`][harpy_analysis]
 and will be executed during the "Analyse Spectrum" phase.
 Some of this procedure is also described on the [BPM filtering page][bpm_filtering].
 
@@ -254,12 +254,12 @@ Some of this procedure is also described on the [BPM filtering page][bpm_filteri
     is done within the cleaning module (see below).
 
 ??? info "Why is cleaning part of the harmonic analysis?"
-    Cleaning is part of the harmonic analysis in `harpy` as the [frequency analysis is done on the v-matrix of the SVD][harpy_ipac]:
+    Cleaning is part of the harmonic analysis in `harpy` as the [frequency analysis is done on the v-matrix of the SVD][harpy_analysis]:
     SVD is used to reduce the noise in the BPM data by selecting only the most important modes and in the same step also to detect bad bpms.
     As this decomposition is a linear transformation, the frequency analysis can be run directly on decomposed v-matrix, without
     having to re-compose the data into the time-domain, saving time and memory.
     The disadvantage is that, as we do not save the SVD matrices, there is no way to only run _cleaning_ without frequency analysis at the moment.
-    For more details, see [doi:10.18429/JACoW-IPAC2022-WEPOMS035][harpy_ipac].
+    For more details, see [this documentation][harpy_analysis] and [doi:10.18429/JACoW-IPAC2022-WEPOMS035][harpy_ipac].
 
 - **Active**:
   If active, the cleaning module is run during the "Analyse Spectrum" phase.
@@ -487,7 +487,6 @@ which is the `python`-internal representation of the accelerator and its setting
 
 [python-docs]: https://pylhc.github.io/omc3/
 [multiturn]: ../multiturn/gui.md
-[harpy_ipac]: https://accelconf.web.cern.ch/ipac2022/papers/wepoms035.pdf
 [bpm_filtering]: ../../measurements/physics/bpm_filtering.md
 [bad_bpms]: ../../measurements/physics/bpm_filtering.md#manual
 [isolation_forest_cleaning]: ../../measurements/physics/bpm_filtering.md#isolation-forest
@@ -496,4 +495,6 @@ which is the `python`-internal representation of the accelerator and its setting
 [gitlab_issue279]: https://gitlab.cern.ch/acc-co/lhc/lhc-app-beta-beating/-/issues/279
 [n_bpm_method]: https://journals.aps.org/prab/abstract/10.1103/PhysRevAccelBeams.20.111002
 [three_bpm_method]: https://repository.cern/records/eny2v-4y338
-[isolation_forest_issue]: https://github.com/pylhc/omc3/issues/184
+[isolation_forest_issue]: https://github.com/pylhc/omc3/issues/184
+[harpy_ipac]: https://accelconf.web.cern.ch/ipac2022/papers/wepoms035.pdf
+[harpy_analysis]: ../../measurements/physics/harpy.md

docs/measurements/physics/harpy.md

@@ -0,0 +1,20 @@
+# Harmonic Analysis with Harpy
+
+This page describes how the harmonic analysis is performed with the `harpy` module.
+If you want to know how to use the `harpy` module, refer to the [`omc3` analysis workflow][omc3_analysis].
+
+!!! todo "Implement this page"
+    Explain how harpy works.
+    Similar to [Malina - Harpy: A Fast, Simple and Accurate Harmonic Analysis with Error Propagation](https://accelconf.web.cern.ch/ipac2022/doi/JACoW-IPAC2022-WEPOMS035.html)
+    but more detail:
+
+    - SVD, Noise cleaning, Noise estimation
+    - Why numpy FFT? What about SUSSIX, LASKAR?
+    - Zero padding
+    - Binning
+    - Error propagation
+    - BPM cleaning
+    - Line identification
+
+
+[omc3_analysis]: ../../packages/omc3/analysis.md

mkdocs.yml

@@ -208,6 +208,7 @@ nav:
       - Error Propagation: measurements/physics/error_propagation.md
       - BPM-Calibration: measurements/physics/bpm_calibration.md
       - BPM-Filtering: measurements/physics/bpm_filtering.md
+      - Harmonic Analysis: measurements/physics/harpy.md
       - Coupling: measurements/physics/coupling.md
       - K-Mod: measurements/physics/kmod.md
       - Linear IR Optics: measurements/physics/ir_linear_optics.md