SbS Coupling and Dispersion Propagation (#491)

Author: JoschD

CHANGELOG.md

@@ -1,5 +1,10 @@
 # OMC3 Changelog
 
+#### 2025-04-03 - v0.24.0 - _jdilly_
+
+- Added:
+  - Additional Propagables: Dispersion (but not really working [#498](https://github.com/pylhc/omc3/issues/498)), Coupling (only forward working [#498](https://github.com/pylhc/omc3/issues/498])).
+
 #### 2025-04-01 - v0.23.01 - _jdilly_, _jgray_
 
 - Changed:

doc/_static/css/custom.css

@@ -272,4 +272,24 @@ em.sig-param span.default_value {
     padding-top: 10px;
     padding-bottom: 5px;
   }
-}
+}
+
+/* Custom styles for bibliography */
+.citation {
+    display: block!important;
+}
+
+.citation .label {
+    display: block;
+    font-weight: bold;
+    margin-bottom: 0.5em;
+}
+
+.citation p {
+    margin: 0;
+    padding-left: 1em;
+}
+
+.citation cite {
+    display: block;
+}

doc/bibliography.rst

@@ -0,0 +1,8 @@
+Bibliography
+************
+
+.. [LangnerDevelopmentsSegmentbySegmentTechnique2015]
+    A. Langner et al.,
+    `Developments of the Segment-by-Segment Technique for Optics Corrections in the LHC,`
+    Proceedings of the 6th International Particle Accelerator Conference (2015).
+    https://doi.org/10.18429/JACoW-IPAC2015-MOPJE054

doc/index.rst

@@ -24,6 +24,13 @@ Package Reference
 
    modules/*
 
+.. toctree::
+   :caption: Bibliography 
+   :maxdepth: 1
+
+   bibliography
+
+
 Citing
 ======
 

doc/modules/definitions.rst

@@ -10,3 +10,7 @@ Definitions
     :members:
     :noindex:
 
+
+.. automodule:: omc3.definitions.optics
+    :members:
+    :noindex:

omc3/__init__.py

@@ -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.23.1"
+__version__ = "0.24.0"
 __author__ = "pylhc"
 __author_email__ = "[email protected]"
 __license__ = "MIT"

omc3/__main__.py

@@ -1,8 +1,20 @@
 from pathlib import Path
+
 this_dir = Path(__file__).parent
+
+# Welcome ---
+print("Welcome to omc3!\n")
+
+# Scripts ---
 scripts = this_dir.glob("[a-zA-Z]*.py")
-print("Welcome to omc3!")
 print("Available entrypoints:\n")
 for script in scripts:
     print(f"omc3.{script.stem}")
+print()
+
+# Modules ---
+modules = this_dir.glob("*/**/__main__.py")
+print("Other Modules:\n")
+for module in modules:
+    print(f"omc3.{module.parent.stem}")
 print()

omc3/definitions/formats.py

@@ -1,6 +1,6 @@
 """
 Formats
--------------
+-------
 
 Recurring formats are defined here.
 """

omc3/definitions/optics.py

@@ -1,11 +1,19 @@
+""" 
+Optics
+------
+
+Definitions for the optics measurements.
+"""
+from __future__ import annotations
+
 from dataclasses import dataclass, fields
 
 import tfs
 from omc3.correction.constants import EXPECTED, DIFF
 from omc3.optics_measurements.constants import (
-    BETA_NAME, AMP_BETA_NAME, ORBIT_NAME, DISPERSION_NAME, NORM_DISP_NAME,
+    ALPHA, BETA_NAME, AMP_BETA_NAME, ORBIT_NAME, DISPERSION_NAME, NORM_DISP_NAME,
     PHASE_NAME, TOTAL_PHASE_NAME, AMPLITUDE, REAL, IMAG, DISPERSION, NORM_DISPERSION,
-    PHASE_ADV, MDL, S, KMOD_BETA_NAME,
+    PHASE_ADV, MDL, S, S_MODEL, KMOD_BETA_NAME,
     EXT, NAME, DELTA, ERR, DRIVEN_TOTAL_PHASE_NAME, DRIVEN_PHASE_NAME, IP_NAME,
     KMOD_IP_NAME, KICK_NAME, BETA, PHASE, ORBIT, F1001_NAME, F1010_NAME, TUNE, RMS, MASKED)
 from omc3.plotting.utils.annotations import ylabels
@@ -37,8 +45,8 @@ class OpticsMeasurement(TfsCollection):
     kick = Tfs(KICK_NAME)
     ip = Tfs(IP_NAME)
     ip_kmod = Tfs(KMOD_IP_NAME)
-    f1001 = Tfs(F1001_NAME, two_planes=False)
-    f1010 = Tfs(F1010_NAME, two_planes=False)
+    f1001: TfsDataFrame = Tfs(F1001_NAME, two_planes=False)
+    f1010: TfsDataFrame = Tfs(F1010_NAME, two_planes=False)
 
     def _get_filename(self, name, plane="") -> str:
         """ Default way `optics_measurements` filenames are defined,
@@ -82,7 +90,7 @@ class ColumnsAndLabels:
     # Other
     needs_plane: bool = True
 
-    def set_plane(self, plane: str):
+    def set_plane(self, plane: str) -> ColumnsAndLabels:
         """ Fixes the plane in a new object. """
         if not self.needs_plane:
             raise AttributeError("Cannot set the plane of a non-planed definition.")
@@ -91,6 +99,13 @@ def set_plane(self, plane: str):
             needs_plane=False,
             **values_fixed_plane,
         )
+    
+    def set_label_formatted(self, name: str) -> ColumnsAndLabels:
+        """ Fixes the label in a new object (for RDTs). """
+        if self._label is None:
+            raise AttributeError("No label defined.")
+        new_label = self._label.format(name)
+        return ColumnsAndLabels(**{f.name: getattr(self, f.name) for f in fields(self) if f.name != "_label"}, _label=new_label)
 
     # Properties ----
     @property
@@ -190,6 +205,7 @@ def delta_label(self):
 # Defined Columns --------------------------------------------------------------
 TUNE_COLUMN =            ColumnsAndLabels(TUNE, _expected_column=f"{EXPECTED}{TUNE}{{0}}",  _label=ylabels['tune'], _text_label='tune')
 BETA_COLUMN =            ColumnsAndLabels(BETA, _label=ylabels['beta'], _text_label='beta', _delta_label=ylabels['betabeat'])
+ALPHA_COLUMN =           ColumnsAndLabels(ALPHA, _label=ylabels['alpha'], _text_label='alpha')
 ORBIT_COLUMN =           ColumnsAndLabels(ORBIT, _label=ylabels['co'], _text_label='orbit')
 DISPERSION_COLUMN =      ColumnsAndLabels(DISPERSION, _label=ylabels['dispersion'], _text_label='dispersion')
 NORM_DISPERSION_COLUMN = ColumnsAndLabels(NORM_DISPERSION, _label=ylabels['norm_dispersion'], _text_label='normalized dispersion')
@@ -198,6 +214,7 @@ def delta_label(self):
 MU_COLUMN =              ColumnsAndLabels(PHASE_ADV, _label=ylabels['phasetot'], _text_label='total phase')
 PHASE_ADVANCE_COLUMN =   ColumnsAndLabels(f'{PHASE_ADV}{{0}}{MDL}', _label=r'Phase Advance [$2 \pi$]', _text_label='phase advance')
 S_COLUMN =               ColumnsAndLabels(S, _label='Location [m]', _text_label='longitudinal location', needs_plane=False)
+S_MODEL_COLUMN =         ColumnsAndLabels(S_MODEL, _label='Location [m]', _text_label='longitudinal location', needs_plane=False)
 
 RDT_AMPLITUDE_COLUMN = ColumnsAndLabels(AMPLITUDE, _label=ylabels['absolute'], _text_label='amplitude', needs_plane=False)  # label needs rdt
 RDT_PHASE_COLUMN =     ColumnsAndLabels(PHASE, _label=ylabels['phase'], _text_label='phase', needs_plane=False)  # label needs rdt
@@ -227,4 +244,4 @@ def delta_label(self):
 }
 
 """ Find the Column Dataclass by column name for RDTs. """
-RDT_COLUMN_MAPPING = {c.column: c for c in [RDT_AMPLITUDE_COLUMN, RDT_PHASE_COLUMN, RDT_IMAG_COLUMN, RDT_REAL_COLUMN]}
+RDT_COLUMN_MAPPING = {c.column: c for c in [RDT_AMPLITUDE_COLUMN, RDT_PHASE_COLUMN, RDT_IMAG_COLUMN, RDT_REAL_COLUMN]}

omc3/model/model_creators/abstract_model_creator.py

@@ -38,6 +38,7 @@
     measurement_madx,
 )
 from omc3.segment_by_segment.propagables import Propagable
+from omc3.segment_by_segment.propagables.coupling import Coupling
 from omc3.segment_by_segment.segments import Segment
 from omc3.utils import iotools, logging_tools