K-modulation scripts (#463)

* added kmod scripts and tests 
* removed old kmod merge and run scripts
* doc
* version 0.19.0

---------

Co-authored-by: JoschD <[email protected]>

Author: fscarlier

.gitignore

@@ -73,7 +73,7 @@ instance/
 
 # Sphinx build directory and sphinx-gallery generated documents
 docs/_build/
-docs/_build/
+doc/_build/
 doc_build/
 .doc_build
 .doc_build/

CHANGELOG.md

@@ -1,10 +1,20 @@
 # OMC3 Changelog
 
+#### 2024-11-13 - v0.19.0 - _fscarlier_, _jdilly_
+
+- Added K-Modulation tools:
+  - `kmod_importer`: Main function to call the following scripts in succession.
+  - `kmod_averages`: Combine k-modulation results into a single file.
+  - `kmod_lumi_imbalance`: Calculate the luminosity imbalance IP1 / IP5 from k-modulation results.
+  - `kmod_import`: Import k-modulation results into an `optics_measurements` directory as `beta_kmod_().tfs` file.
+
+- Removed:
+  - Old k-modulation scripts: Functionality is either in k-mod GUI or in newly added scripts.
+
 #### 2024-11-11 - v0.18.1 - _jdilly_
 
 - Fixed:
   - Setting sparkprops wrong in `knob_extractor` fixed.
-  
 
 #### 2024-10-29 - v0.18.0 - _jgray_
 
@@ -17,8 +27,7 @@
 - Fixed:
   - Fixed the `response_twiss` when updating the response matrix when calculating the global correction.
 
-
-#### 2024-10-29 - v0.17.0 - _jdilly_ 
+#### 2024-10-29 - v0.17.0 - _jdilly_
 
 - Added:
   - Optics Measurements: `analyse_dpp` parameter, to analyse only files with a specific DPP for tune, phase and (C)RDTs.

README.md

@@ -40,15 +40,15 @@ Codes can then be run with either `python -m omc3.SCRIPT --FLAG ARGUMENT` or cal
 #### Main Scripts
 
 Main scripts to be executed lie in the [`/omc3`](omc3) directory. These include:
-- `global_correction.py` to calculate corrections from measurement files.
 - `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.
+- `kmod_importer.py` to average, import and calculate lumi-imbalace K-modulation results.
+- `knob_extractor.py` to extract from `NXCALS` the value of given knobs in the machine at a given time.
 - `model_creator.py` to generate optics models required for optics analysis.
+- `global_correction.py` to calculate corrections from measurement files.
 - `response_creator.py` to provide correction response files.
-- `run_kmod.py` to analyze data from K-modulation and return the measured optics functions.
 - `tbt_converter.py` to convert different turn by turn data types to `SDDS`, potentially adding noise.
 - `amplitude_detuning_analysis.py` to perform amp. det. analysis on optics data with tune correction.
-- `knob_extractor.py` to extract from `NXCALS` the value of given knobs in the machine at a given time.
+- `madx_wrapper.py` to start a `MAD-X` run with a file or string as input.
 
 #### Plotting Scripts
 
@@ -58,6 +58,7 @@ Plotting scripts for analysis outputs can be found in [`/omc3/plotting`](omc3/pl
 - `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.
+- `plot_kmod_results.py` to plot the beta and waist of the K-modulation results.
 
 #### Other Scripts
 
@@ -67,7 +68,10 @@ Other general utility scripts are in [`/omc3/scripts`](omc3/scripts):
 - `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.
 - `fake_measurement_from_model.py` to create a fake measurement based on a model TWISS file.
 - `betabeatsrc_output_converter.py` to convert outputs from our old codes to `omc3`'s new standardized format.
-- `linfile_clean.py` to automatically clean given columns in lin files. 
+- `linfile_clean.py` to automatically clean given columns in lin files.
+- `kmod_average.py` to calculate the average of multiple K-modulation measurements.
+- `kmod_import.py` to import a K-modulation measurement into an optics-measurement directory.
+- `kmod_lumi_imbalace.py` to calculate the luminosity imbalance between two IPs from averaged K-modulation files.
 
 Example use for these scripts can be found in the [`tests`](tests) files.
 Documentation including relevant flags and parameters can be found at <https://pylhc.github.io/omc3/>.

doc/entrypoints/analysis.rst

@@ -9,9 +9,3 @@ Analysis
 .. automodule:: omc3.amplitude_detuning_analysis
     :members:
     :noindex:
-
-
-.. automodule:: omc3.run_kmod
-    :members:
-    :noindex:
-

doc/entrypoints/plotting.rst

@@ -26,6 +26,11 @@ Plotting
     :noindex:
 
 
+.. automodule:: omc3.plotting.plot_kmod_results
+    :members:
+    :noindex:
+
+
 .. automodule:: omc3.plotting.plot_bbq
     :members:
     :noindex:

doc/entrypoints/scripts.rst

@@ -6,7 +6,17 @@ Scripts
     :noindex:
 
 
-.. automodule:: omc3.scripts.merge_kmod_results
+.. automodule:: omc3.scripts.kmod_averages
+    :members:
+    :noindex:
+
+
+.. automodule:: omc3.scripts.kmod_import
+    :members:
+    :noindex:
+
+
+.. automodule:: omc3.scripts.kmod_lumi_imbalance
     :members:
     :noindex:
 

doc/modules/kmod.rst

@@ -11,7 +11,7 @@
 __title__ = "omc3"
 __description__ = "An accelerator physics tools package for the OMC team at CERN."
 __url__ = "https://github.com/pylhc/omc3"
-__version__ = "0.18.1"
+__version__ = "0.19.0"
 __author__ = "pylhc"
 __author_email__ = "[email protected]"
 __license__ = "MIT"