+
+
+ 
+ 
+ 
- 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
+ 
- 
- 
+ 
- 
- 
- 
- 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
or 
: shows some quick tips for using the GUI.
+
+
: shows the error log for debugging.
+
+!!! tip "Navigating Plots Tip"
+ To pan in any of the plots, use Ctrl+LeftClick and drag the mouse.
+
+The following pages are available detailing the tabs and how to use them:
+
+- [Input](input.md){.rdtfeeddown_tab-link} tab: for how to input files to produce an analysable format.
+- [Validation](validation.md){.rdtfeeddown_tab-link} tab: for how to use that analysable format to plot the RDT response as a function of crossing angle amongst another analyses.
+- [Correction](correction.md){.rdtfeeddown_tab-link} tab: for how to quantify the response of RDT for a constant corrector powering, between two crossing angles (i.e. assuming linearity) and use that to match to the analysable format measurement.
+
diff --git a/docs/guis/rdt_feeddown/input.md b/docs/guis/rdt_feeddown/input.md
new file mode 100644
index 00000000..ac850349
--- /dev/null
+++ b/docs/guis/rdt_feeddown/input.md
@@ -0,0 +1,71 @@
+# Input Tab of the RDTfeeddown GUI
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+
+
+
+ 
-
+ 
-
+ While keeping the AC-Dipole amplitude in the horizontal plane constant (but not zero, to avoid weird AC-Dipole behaviour and to see if there is coupling effects), @@ -183,12 +185,16 @@ on how to optimize the analysis and only need to be applied where necessary. which might differ a bit from the actual window if `Autotunes` are used.
+
+
+
-
+ 
-
+ 
-
+ Update Lin-File.
-
+ 
-
+ 
-
+ After local corrections, we can move to having 3 bunches (each below $10^{10}$ppb) evenly spaced along the ring.
It is possible tp "mask" some of the BLMs, which means making sure they won't trigger any beam dump. They are essentially ignored in the interlocked system when masked. +
It is possible to "mask" some of the BLMs, which means making sure they won't trigger any beam dump. They are essentially ignored in the interlocked system when masked.
There should be a pre-made setting for this.
Only if measuring at injection, ask the EIC to deactivate this setting. +
The calculated global correction are really corrections and should be trimmed in with a positive sign.
The tunes should be moved to a working point with a large tune separation, such as $Q_x = 0.28 / Q_y = 0.31$, to allow for maximum modulation amplitude. + Pay attention to potential resonance crossings.
See the [K-Mod pages][kmod_app]. +
In case of any (design) orbit excursion in the quadrupoles, enable orbit feedback to avoid a change of the CO around the ring. - Caveat: for the determination of the crossing angles, orbit feedback should be off. -
In case of any (design) orbit excursion in the quadrupoles, enable orbit feedback to avoid a change of the CO around the ring. + The status is visible in the top right corner of the GUI. +
Otherwise modulation and feedback would work against each other. + The status is visible in the top right corner of the GUI.
Fire up the [K-Mod application][kmod_app]. - There two options are available: - - IP Modulation : Runs a modulation on both quadrupoles closest to the selected IP. - - Single circuit modulation : Runs a modulation on a selected quadrupole circuit (used for measuring the beta-functions in IR4, where BSRT is located). -
-Choose a modulation current such that the change in tune is roughly 0.01. - This can either be done by looking up old shifts with similar optics or by increasing the amplitude until satisfactory tune change is observed. - Modulation frequency is chosen by the system, with higher modulation amplitude resulting in lower modulation frequency. -
As no automatic logging of the modulation is implemented for now, parameters should be logged in the logbook. - Parameters to log are: `Starttime`, `Endtime`, `Modulation current`, `IP`, other comments such as $\beta^{*}$, status of the `OFB`, is significant tunejitter/-jump observed. -
After the analysis, a window should open to allow for extraction of the data from `Timber`. - Alternatively, `Extract previous trim` can be used. - Saving in a separate directory with a descriptive name is recommended (e.g. `Kmod_IPX_beta_beforeCorrection_starttime`) and should be added to the modulation logbook entry. +
See the [following page][kmod_run] for how to perform a modulation of the desired circuit. + Check from the modulation graph for the quality of the modulation and data.
Run the python codes on the extracted Timber data to get the $\beta$ you need. - As of now, only the Kmod analysis from `Beta-Beat.src` can be called from the K-Modulation GUI for the case of an analysis of an IP-Modulation. - Codes and some documentation may be found [for `Python2`][kmod_python2]{target=_blank} and [for `Python3`][kmod_python3]{target=_blank}. +
Analysis is now launched directly from the `Pykmod` app. + See [this page][kmod_analysis] for details on how to analyze and export the data.
The results of the analysis should be located in the previously specified working directory and can be checked by eye using a text editor of choice.
+- [ ] The results are useful to compute optics corrections.
+ See the [Beta-Beat GUI page][beta_beat_gui] for how to import the results.
Using this [script][get_kmod_files_python2]{target=_blank}, the results can be brought in a form which is readable for the BBGUI and can then be used to calculate a correction.
- If results are satisfactory, both `Python2` and `Python3` should create a file called `lsa_results.tfs`, which can be uploaded using the LSA optics uploader for other users to access data.
- This procedure needs global corrections to be trimmed in the machine first, so optics and *global coupling* should be taken care of beforehand.
+ This procedure needs global corrections to be trimmed in the machine first, so optics and _global coupling_ should be taken care of beforehand.
- - [ ] Import Results Into the Beta-Beat GUI
+
-
- - [ ] Use in Beta-Beat GUI for Correction
-
-
*[CO]: Closed Orbit
*[BSRT]: Beam Synchrotron Radiation Telescope
*[OFB]: Orbit Feed Back
*[LSA]: LHC Software Architecture
[kmod_app]: ../../guis/kmod/gui.md
-[get_kmod_files_python2]: https://github.com/pylhc/Beta-Beat.src/blob/master/kmod/gui2beta/get_kmod_files.py
-[kmod_python2]: https://github.com/pylhc/Beta-Beat.src/blob/master/kmod/gui2beta/gui2kmod.py
-[kmod_python3]: https://github.com/pylhc/omc3/blob/master/omc3/run_kmod.py
+[kmod_run]: ../../guis/kmod/modulating.md
+[kmod_analysis]: ../../guis/kmod/analyzing.md
+[kmod_method]: ../../measurements/physics/kmod.md
+[beta_beat_gui]: ../../guis/betabeat/gui.md
diff --git a/docs/measurements/procedures/rigid_waist_shift.md b/docs/measurements/procedures/rigid_waist_shift.md
index cebe7e9b..c355af92 100644
--- a/docs/measurements/procedures/rigid_waist_shift.md
+++ b/docs/measurements/procedures/rigid_waist_shift.md
@@ -5,13 +5,13 @@
??? info "The Procedure in Short"
- This methods aims to find the MQSX correction settings that would minimize betatron coupling and its impact on beam size *at the IP*.
+ This methods aims to find the MQSX correction settings that would minimize betatron coupling and its impact on beam size _at the IP_.
The method breaks the symmetry of the optics in the IR and forces local coupling RDTs to leak throughout the machine, which makes them measurable through the $|C^{-}|$.
After global corrections are done and trimmed in the machine, one applies a rigid waist shift in a given IR and scans the colinearity knob for the value that minimizes the $|C^{-}|$.
These settings, when taking away the rigid waist shift, will minimize local coupling and its impact at the IP.
- Additional info can be found in Felix's 2021 IPAC paper[^SoubeletIPACLocalCouplingCorrection].
+ Additional info can be found in Felix's 2021 IPAC paper[^SoubeletIPACLocalCouplingCorrection] and 2023 PRAB paper[^SoubeletPRABLocalCouplingCorrection].
## Rigid Waist Shift & LSA Knobs
@@ -20,7 +20,7 @@ Some details about the creation of these knobs and their addition in LSA can be
### Knob Setting Convention
-Two different knobs are used for the waist shift that need to be trimmed in:
+Two different knobs are used for the waist shift that need to be trimmed in:
- The triplets knob, which generates the waist shift itself.
- The independent quadrupoles knob (Q4 - Q10), which re-matches the optics.
@@ -34,13 +34,13 @@ The knob setting is defined as follows, with regards to Beam1 (reverse for Beam2
### The Knobs in LSA
Since the triplet knob for a unit setting of +$1$ is the exact opposite magnet powering of the knob for a unit setting of -$1$, only a single triplet knob per IP has been added to LSA, which can then be trimmed with a factor of $\pm1$.
-On the other hand, the re-matching quadrupole knobs are specific to a given direction of the shift, so two of them per IP (one per direction) were added to LSA, with the *pos* and *neg* suffixes.
+On the other hand, the re-matching quadrupole knobs are specific to a given direction of the shift, so two of them per IP (one per direction) were added to LSA, with the _pos_ and _neg_ suffixes.
These should always be trimmed with a factor of $1$.
As a consequence, respect the following rules when applying the knobs below:
- - When trimming the triplet knob with a factor of +$1$, use the *pos* re-matching quadrupoles knob.
- - When trimming the triplet knob with a factor of -$1$, use the *neg* re-matching quadrupoles knob.
+- When trimming the triplet knob with a factor of +$1$, use the _pos_ re-matching quadrupoles knob.
+- When trimming the triplet knob with a factor of -$1$, use the _neg_ re-matching quadrupoles knob.
??? info "LSA Triplets Knobs"
@@ -64,10 +64,10 @@ As a consequence, respect the following rules when applying the knobs below:
??? example "An Example"
We wish to implement the waist shift at IP1, shifting the waist to the left of IP (for Beam1).
- To do so we need to apply the *LHCBEAM/MD_ATS_2020-05_04_BX_RigidWaistShift_Triplet_IP1* with a factor of +$1$.
+ To do so we need to apply the _LHCBEAM/MD_ATS_2020-05_04_BX_RigidWaistShift_Triplet_IP1_ with a factor of +$1$.
- Since we used a +$1$ factor on the triplet knob, the corresponding re-matching quadrupoles knobs to use are those with the *pos* suffix, and they should be trimmed with a factor +$1$.
- The knobs to trim are then: *LHCBEAM/MD_ATS_2022_05_04_B1_RigidWaitsShift_IP1pos* and *LHCBEAM/MD_ATS_2022_05_04_B2_RigidWaitsShift_IP1pos*.
+ Since we used a +$1$ factor on the triplet knob, the corresponding re-matching quadrupoles knobs to use are those with the _pos_ suffix, and they should be trimmed with a factor +$1$.
+ The knobs to trim are then: _LHCBEAM/MD_ATS_2022_05_04_B1_RigidWaitsShift_IP1pos_ and _LHCBEAM/MD_ATS_2022_05_04_B2_RigidWaitsShift_IP1pos_.
!!! warning "Value of the Waist Shift"
The waist shift from the generated knobs should be of about 43 to 44cm in either direction.
@@ -77,7 +77,7 @@ As a consequence, respect the following rules when applying the knobs below:
## Preliminary Setup
- [ ] Publish Results
-
- [ ] Do Global Corrections
- **Optional:** Scan the Colinearity Knob to Check Conditions
@@ -158,7 +158,7 @@ Keep in mind that this does Beam1 and Beam2 at the same time, but different IPs
[^SoubeletIPACLocalCouplingCorrection]:
??? abstract "Prospect for Interaction Region Local Coupling Correction in the LHC Run 3, `F. Soubelet, and T. Persson, and R. Tomás, and O. Apsimon, and C.P. Welsch`, [International Particle Accelerator Conference, 2021](https://accelconf.web.cern.ch/ipac2021/papers/mopab007.pdf){target=_blank}"
```
- @inproceedings{soubeletProspectInteractionRegion2021,
+ @inproceedings{soubeletProspectInteractionRegion2021,
author={Soubelet, F. and Persson, T. and Tomás, R. and Apsimon, O. and Welsch, C.P.},
booktitle={Proceedings of the 12th International Particle Accelerator Conference},
title={Prospect for Interaction Region Local Coupling Correction in the LHC Run 3},
@@ -168,6 +168,25 @@ Keep in mind that this does Beam1 and Beam2 at the same time, but different IPs
}
```
+[^SoubeletPRABLocalCouplingCorrection]:
+ ??? abstract "Rigid Waist Shift: A New Method for Local Coupling Corrections in the LHC Interaction Regions, `F. Soubelet, T. Persson, R. Tomás, O. Apsimon and C. Welsch`, [Phys. Rev. Accel. Beams 25, 051001, 2023](https://link.aps.org/doi/10.1103/PhysRevAccelBeams.26.051001){target=_blank}"
+ ```
+ @article{Soubelet2023,
+ author = {Soubelet, Felix and Persson, Tobias and Tomás, Rogelio and Apsimon, Oznur and Welsch, Carsten P.},
+ doi = {10.1103/PhysRevAccelBeams.26.051001},
+ issue = {5},
+ journal = {Phys. Rev. Accel. Beams},
+ month = {May},
+ numpages = {13},
+ pages = {051001},
+ publisher = {American Physical Society},
+ title = {Rigid waist shift: A new method for local coupling corrections in the LHC interaction regions},
+ url = {https://link.aps.org/doi/10.1103/PhysRevAccelBeams.26.051001},
+ volume = {26},
+ year = 2023
+ }
+ ```
+
*[rigid waist shift]: Shifting the waist of the beam from the IP point by un-balancing the powering of the left and right triplets in the IR.
*[MQSX]: The skew quadrupole correctors located next to Q3
*[LSA]: LHC Software Architecture
@@ -178,4 +197,4 @@ Keep in mind that this does Beam1 and Beam2 at the same time, but different IPs
*[colinearity knob]: This is a powering setting of the MQSXs, which corresponds to a K1S value of ±1E-4 m^-2.
[rws_gallery]: https://fsoubelet.github.io/PyhDToolkit/gallery/demo_lhc_rigid_waist_shift.html
-[logbook_entry]: https://be-op-logbook.web.cern.ch/elogbook-server/GET/showEventInLogbook/3545713
\ No newline at end of file
+[logbook_entry]: https://be-op-logbook.web.cern.ch/elogbook-server/GET/showEventInLogbook/3545713
diff --git a/docs/measurements/procedures/xing_scan.md b/docs/measurements/procedures/xing_scan.md
index 486cfb5a..870bb3b3 100644
--- a/docs/measurements/procedures/xing_scan.md
+++ b/docs/measurements/procedures/xing_scan.md
@@ -4,4 +4,4 @@
Please keep in mind the [general checks](general_checks.md) for measurements.
??? info "The Procedure in Short"
- Little bit about the purpose and concept.
\ No newline at end of file
+ Little bit about the purpose and concept.
diff --git a/docs/omc_team/ideas.md b/docs/omc_team/ideas.md
index ed580587..f85d811d 100644
--- a/docs/omc_team/ideas.md
+++ b/docs/omc_team/ideas.md
@@ -1,60 +1,13 @@
# Future MD Ideas
-## Run 3 MDs Ideas
-
-### Linear Optics Related
-
-* 3 New ballistic optics flavors:
- * Ballistic with beta* de-squeeze at top energy to reach above 1Km beta in dipoles, to study quadrupolar errors in dipoles. This is specially important in view of HL-LHC D2 b2 errors.
- * Telescopic for tune jitter measurements with enhanced arcs.
- * Ballistic with large vertical dispersion.
-* Half integer tune.
-* 60 degrees arc cell phase advance for HE-LHC (or 1/3 HE-LHC), and for improving knowledge on LHC itself as phase advance samples errors differently and arc sextupoles are factor ~2 weaker (more linear machine): arc errors, MCS shifts + coupling, BPM aberrations (beam signal closer to pure sin).
-* Experience HL-LHC-like injection optics with beta*=6m (pilots only).
-* Look at 11 T flux jumps with TbT data, possibly using a new optics with enhanced beta functions.
-* 2 possible experiments with TOTEM to understand the assymetry of the local dispersion in IR5:
- * Measurements with flat orbit, >60 bunches.
- * Measurements with ballistic optics.
-* Non-90 degrees arc cell phase advance to ease correction of errors in the arcs (reduce the knob degeneracy of orbit bumps at sextupoles).
-* Measure optics at smallest beta* for a long time, looking for an effect as in SKEKB where Final Focus quadrupole strength drifted by 0.01%. https://kds.kek.jp/event/39396/
-* Try Closed Orbit Distortion optics measurement as in SuperKEKB with 3-6 orbit correctors per plane and orbit fitting.
-
-### Coupling Related
-
-* Tilting triplets to correct local coupling to operate without MQSX.
-* Switching off MCS and main sextupoles in one arc to evaluate possible (systematic) vertical or horizontal misalignment of dipoles by measuring coupling and beta-beating during the b3 decay.
-In a previous MD there was a quadratic coupling increase due to the orbit bump in the arc (maybe the one without MS, tbc).
-* Crazy MD for this, could be shifting the edge of some dipoles up to see change in coupling.
-* Tilting a triplet quadrupole to check validity of the tilt measurement (with and/or without beam).
-
-### BPM related
-
-* Measure bad BPMs with low and high intensities to detect possible issues with the comparator (transistor).
-Also swap connections between good and bad BPM to identified.
-* Have one BPM unplugged to detect its noise until next technical stop.
-* Momentum compaction factor from Qs versus Voltage.
-* Snap-back with forced 3D oscillations (optics, chroma,...).
-* Maybe not OMC: 24h pilot at top energy to use damped beam for BSRT resolution measurement.
-* 0.5 um bunch from new injector chain?? Good for optics measurements, BSRT calibration etc.
-
-### K-mod related
-
-* K-Modulation with Xing angle and OFB off for Leon's Xing angle reconstruction.
-* Arc K-modulation.
-* K-modulation in IR4 during the energy ramp.
-* Reduce to one the DCCTs per circuit with pilot in the machine and ATS optics to see the impact of 2 DCCTs.
- Michele Martino also proposes increasing in 1ppm the noise of the DCCTs in one or all dipole PCs to see impact on tune jitter.
-
-### Non-Linear Optics Related
-
-* Commissioning?: Measure amplitude detuning coming from CMS solenoid by having the on and off measurements.
-* IR non-linear corrector offsets measurement.
-* Emittance growth from octupoles and chroma.
-* Amplitude detuning measurement versus crossing angle with b6 corrector on, for 5 crossing angles to evaluate performance of the technique for b6 correction.
-* Amplitude dependent optics: Dedicated settings at injection as PoP (Thomas & Barbara), alternative techniques in parallel (K-modulation with decohered beams and amplitude dependent segment-by-segment).
-* IR2 non-linear correction -> Dedicated squeeze for IR2 to allow for good triplet characterization to shed light on b4.
-* Amplitude detuning in ballistic optics.
-* ADT for single kicks.
-* b5 RDTs.
-* Measurement and correction of a3 RDTs at injection for lifetime optimization (correcting with MSSX and MSS).
-* Reduce RF voltage to decrease synchrotron tune to limit the emittance blow-up during excitation with driven and natural tunes close to each other.
+!!! note "CodiMD"
+ The content of this page is hosted on CodiMD for easy editing.
+ But you need to visit [the original codimd page](https://codimd.web.cern.ch/s/bG7VxhdGM){target=_blank}
+ to be able to login and edit!
+
+
diff --git a/docs/packages/about.md b/docs/packages/about.md
index a0ad44ba..ea4bf4c1 100644
--- a/docs/packages/about.md
+++ b/docs/packages/about.md
@@ -1,18 +1,17 @@
# The OMC Python Packages
-| Package | Description | Version | Documentation | Wiki |
-| :------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------: | :--------------------------------------------------------------------: |
-| [**OMC3**][omc3]{target=\_blank} | Frequency analysis, optics computation from turn-by-turn data, corrections calculations and results plotting | [][omc3_pypi]{target=\_blank} | [:fontawesome-solid-book:][omc3_doc]{target=\_blank} | [:fontawesome-solid-circle-question:](omc3/about.md) |
-| [**TFS-Pandas**][tfspandas]{target=\_blank} | TFS files I/O functionality | [][tfs_pypi]{target=\_blank} | [:fontawesome-solid-book:][tfspandas_doc]{target=\_blank} | |
-| [**Turn-by-Turn**][turnbyturn]{target=\_blank} | Particle accelerators turn-by-turn BPM measurements I/O functionality | [][tbt_pypi]{target=\_blank} | [:fontawesome-solid-book:][turnbyturn_doc]{target=\_blank} | |
-| [**SDDS**][sdds]{target=\_blank} | SDDS files I/O functionality | [][sdds_pypi]{target=\_blank} | [:fontawesome-solid-book:][sdds_doc]{target=\_blank} | |
-| [**PyLHC-Tools**][pylhc]{target=\_blank} | Useful OMC-related scripts | [][pylhc_pypi]{target=\_blank} | [:fontawesome-solid-book:][pylhc_doc]{target=\_blank} | [:fontawesome-solid-circle-question:](pylhc/about.md) |
-| [**PyLHC-Submitter**][pylhc_submitter]{target=\_blank} | Wrapper for HTCondor job submission | [][pylhc_submitter_pypi]{target=\_blank} | [:fontawesome-solid-book:][pylhc_submitter_doc]{target=\_blank} | [:fontawesome-solid-circle-question:](pylhcsubmitter/job_submitter.md) |
-| [**Optics-Functions**][optics_functions]{target=\_blank} | Calculate various beam optics functions from TFS-Dataframes | [][optics_functions_pypi]{target=\_blank} | [:fontawesome-solid-book:][optics_functions_doc]{target=\_blank} | |
-| [**Generic-Parser**][generic_parser]{target=\_blank} | Entrypoint argument parser functionality | [][generic_parser_pypi]{target=\_blank} | [:fontawesome-solid-book:][generic_parser_doc]{target=\_blank} | |
-| [**Example Study Scripts**][mess]{target=\_blank} | Collection of example MAD-X studies | [][mess_releases]{target=\_blank} | | [:fontawesome-solid-circle-question:](mess/about.md) |
-| [**Beta-Beat.src**][betabeatsrc]{target=\_blank} | Frequency analysis, optics computation from turn-by-turn data and corrections calculations | [][betabeatsrc_releases]{target=\_blank} | [:fontawesome-solid-book:][betabeatsrc_doc]{target=\_blank} | |
-
+| Package | Description | Version | Documentation | Wiki |
+|-:--------------------------------------------------------|-:------------------------------------------------------------------------------------------------------------|-:-:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-:-:--------------------------------------------------------------|-:-:--------------------------------------------------------------------|
+| [**OMC3**][omc3]{target=\_blank} | Frequency analysis, optics computation from turn-by-turn data, corrections calculations and results plotting | [][omc3_pypi]{target=\_blank} | [:fontawesome-solid-book:][omc3_doc]{target=\_blank} | [:fontawesome-solid-circle-question:](omc3/about.md) |
+| [**TFS-Pandas**][tfspandas]{target=\_blank} | TFS files I/O functionality | [][tfs_pypi]{target=\_blank} | [:fontawesome-solid-book:][tfspandas_doc]{target=\_blank} | |
+| [**Turn-by-Turn**][turnbyturn]{target=\_blank} | Particle accelerators turn-by-turn BPM measurements I/O functionality | [][tbt_pypi]{target=\_blank} | [:fontawesome-solid-book:][turnbyturn_doc]{target=\_blank} | |
+| [**SDDS**][sdds]{target=\_blank} | SDDS files I/O functionality | [][sdds_pypi]{target=\_blank} | [:fontawesome-solid-book:][sdds_doc]{target=\_blank} | |
+| [**PyLHC-Tools**][pylhc]{target=\_blank} | Useful OMC-related scripts | [][pylhc_pypi]{target=\_blank} | [:fontawesome-solid-book:][pylhc_doc]{target=\_blank} | [:fontawesome-solid-circle-question:](pylhc/about.md) |
+| [**PyLHC-Submitter**][pylhc_submitter]{target=\_blank} | Wrapper for HTCondor job submission | [][pylhc_submitter_pypi]{target=\_blank} | [:fontawesome-solid-book:][pylhc_submitter_doc]{target=\_blank} | [:fontawesome-solid-circle-question:](pylhcsubmitter/job_submitter.md) |
+| [**Optics-Functions**][optics_functions]{target=\_blank} | Calculate various beam optics functions from TFS-Dataframes | [][optics_functions_pypi]{target=\_blank} | [:fontawesome-solid-book:][optics_functions_doc]{target=\_blank} | |
+| [**Generic-Parser**][generic_parser]{target=\_blank} | Entrypoint argument parser functionality | [][generic_parser_pypi]{target=\_blank} | [:fontawesome-solid-book:][generic_parser_doc]{target=\_blank} | |
+| [**Example Study Scripts**][mess]{target=\_blank} | Collection of example MAD-X studies | [][mess_releases]{target=\_blank} | | [:fontawesome-solid-circle-question:](mess/about.md) |
+| [**Beta-Beat.src**][betabeatsrc]{target=\_blank} | Frequency analysis, optics computation from turn-by-turn data and corrections calculations | [][betabeatsrc_releases]{target=\_blank} | [:fontawesome-solid-book:][betabeatsrc_doc]{target=\_blank} | |
## The OMC Python Ecosystem
@@ -34,20 +33,18 @@ The environment is located at `/afs/cern.ch/eng/sl/lintrack/omc_python3/` and ca
- Point to the Python executable directly (`/afs/cern.ch/eng/sl/lintrack/omc_python3/bin/python`) to execute your programs.
!!! warning "Modifying the Environment"
- Please do not try to modify this environment.
+ You cannot modify this environment, [unless you are one of the maintainers](development/managing.md).
Should you need specific packages, reach out to us or consider [setting up your own environment](development/howto_venv.md#creating-virtual-environments-with-acc-py) from our `Acc-Py` distribution.
??? question "Python 2 Environment"
We do have a `miniconda2` installation in `lintrack` for legacy Python2 codes.
This distribution is frozen and the use of Python 2 codes should be avoided as much as possible.
-
[accpy_docs]: https://wikis.cern.ch/display/ACCPY/Accelerating+Python+Home
[betabeatsrc]: https://github.com/pylhc/Beta-Beat.src
[betabeatsrc_doc]: https://pylhc.github.io/Beta-Beat.src
[betabeatsrc_releases]: https://github.com/pylhc/Beta-Beat.src/releases
-
[tfspandas]: https://github.com/pylhc/tfs
[tfspandas_doc]: https://pylhc.github.io/tfs
[turnbyturn]: https://github.com/pylhc/turn_by_turn
@@ -74,4 +71,4 @@ The environment is located at `/afs/cern.ch/eng/sl/lintrack/omc_python3/` and ca
[pylhc_submitter_pypi]: https://pypi.org/project/pylhc-submitter/
[sdds_pypi]: https://pypi.org/project/sdds/
[tbt_pypi]: https://pypi.org/project/turn-by-turn/
-[tfs_pypi]: https://pypi.org/project/tfs-pandas/
\ No newline at end of file
+[tfs_pypi]: https://pypi.org/project/tfs-pandas/
diff --git a/docs/packages/development/contributing.md b/docs/packages/development/contributing.md
index 90fe7324..8bcf4544 100644
--- a/docs/packages/development/contributing.md
+++ b/docs/packages/development/contributing.md
@@ -5,18 +5,18 @@ We welcome contributions, but before you do, please read the following guideline
## Submission context
-#### Got a question or problem?
+### Got a question or problem?
If you have questions on some of the packages' functionality, and the available documentation does not provide answers, you can submit them as new issues on GitHub.
-If you spot missing parts in the documentation, feel free to report it in an issue and open a Pull Request that fixes it.
+If you spot missing parts in the documentation, feel free to report it in an issue and open a Pull Request that fixes it.
-#### Found a bug?
+### Found a bug?
If you found a bug in the source code, you can help us by submitting a bug report in a new issue on GitHub.
If you wish to contribute a solution, you can submit a Pull Request with a fix.
However, before doing so, please read the submission guidelines bellow.
-#### Missing a feature?
+### Missing a feature?
You can request a new feature by opening an issue on GitHub.
If you would like to implement a new feature, please submit an issue with a proposal first, to be sure that it is necessary and appropriate to the package, and to discuss implementation details.
@@ -29,13 +29,13 @@ This will also allow us to better coordinate our efforts, prevent duplication of
## Submission guidelines
-#### Submitting an issue
+### Submitting an issue
Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of fixes or workarounds readily available.
If you are submitting a bug report, please also provide a minimal scenario to reproduce it.
-#### Submitting a Pull Request (PR)
+### Submitting a Pull Request (PR)
First, search GitHub for an open or closed PR that relates to your submission.
If you do not find a related issue or PR, or if your PR is the implementation for an issue you open, go ahead.
@@ -51,7 +51,7 @@ If you do not find a related issue or PR, or if your PR is the implementation fo
If new changes are suggested, make the required updates and push the changes again.
Please do not require a review until all the quality checks pass.
-#### Quality checks
+### Quality checks
- Unit and accuracy tests are run automatically through CI [Github Actions][gh_actions]{target=_blank}.
A `README.md` file in the `.github/workflows` directory details our CI jobs.
@@ -70,18 +70,18 @@ In case you want to contribute to a package's development, you should install it
```bash
git clone https://github.com/pylhc/package_name
-pip install --editable package_name
+python -m pip install --editable package_name
```
??? tip "Installing Extras"
You can install extra dependencies (as defined in `setup.py`) suited to your use case with the following commands:
```bash
- pip install --editable package_name[test]
- pip install --editable package_name[test,doc]
- pip install --editable package_name[all]
+ python -m pip install --editable package_name[test]
+ python -m pip install --editable package_name[test,doc]
+ python -m pip install --editable package_name[all]
```
-
+
For development purposes, we recommend using the `all` extra to be fully set up.
### Naming Conventions
diff --git a/docs/packages/development/howto_release.md b/docs/packages/development/howto_release.md
index 71218a3b..c1320bea 100644
--- a/docs/packages/development/howto_release.md
+++ b/docs/packages/development/howto_release.md
@@ -15,4 +15,4 @@ A `publish` workflow will be triggered, build source distribution and wheels and
*[PyPI]: The Python Package Index
[github_actions]: https://github.com/features/actions
-[pypi_releases]: https://pypi.org/search/?q=pylhc
\ No newline at end of file
+[pypi_releases]: https://pypi.org/search/?q=pylhc
diff --git a/docs/packages/development/howto_venv.md b/docs/packages/development/howto_venv.md
index 5f512503..c3aca48c 100644
--- a/docs/packages/development/howto_venv.md
+++ b/docs/packages/development/howto_venv.md
@@ -31,6 +31,7 @@ The default distribution is recommended but installation is identical for other
As of writing this walk-through, this corresponds to the `acc-py-2020.11-installer.sh` file.
The installer itself is an executable to be called from the command line.
Once the file is downloaded, run it at the command line (you might need to `chmod u+x` the file):
+
```bash
bash acc-py-2020.11-installer.sh
```
@@ -54,30 +55,35 @@ You are now done with the installation step.
## Creating Virtual Environments with Acc-Py
To make the command line tools available in the current shell, `source` the `setup.sh` script in the installed `Acc-Py` distribution:
+
```bash
source dist_location/base/2020.11/setup.sh
```
-You should see a confirmation message output that reads:
-```
+You should see a confirmation message output that reads:
+
+```bash
=> Acc-Py base 2020.11 is now active within this shell.
```
You now have access to the `acc-py` command line tool, which you can verify by running `acc-py -h` and checking that you get the help command output.
The command to create a virtual environment is based on the built-in [venv][venv_module]{target=_blank} module and should feel familiar if you know `venv`.
To create a virtual environment, run:
+
```bash
acc-py venv /path/to/environment/
```
This will create a virtual environment at `/path/to/environment/`.
To activate this environment, run:
+
```bash
source /path/to/environment/bin/activate
```
You can confirm you are running the appropriate Python with `which python`, which should point to `/path/to/environment/bin/python`.
You can then install packages in this environment with:
+
```bash
python -m pip install
+ Use any machine with VSCode installed to connect to a remote machine and continue developing on it,
+ e.g. you can store your files on `afs` and connect to them through `lxplus`, working on them as if they were present locally.
+ Check the [CERN Knowledge Base][vscode_lxplus]{target=_blank} for more information.
+- [Python support][vscode_python]{target=_blank}:
+ Make use of static type checking and auto-completion. Interact with the code via an easy-to-use debugger.
+- [Debugging][vscode_debugging]{target=_blank}:
+ Enables you to stop your program at any point and interact with it as well as inspect variables and their values.
+- [Interactive Python][vscode_interactive_python]{target=_blank}:
+ Use any script as if it were a jupyter notebook, allowing you to run code snippets in real time and inspect variables.
+- [Integrated Testing][vscode_testing]{target=_blank}:
+ Use the `pytest` framework to easily write and run tests, which can be individually run or all at once directly from the editor.
+- [Great Extendibility][vscode_marketplace]{target=_blank}:
+ Many extensions are available, making VSCode a great tool for many different use cases and programming languages (e.g. [LaTeX][vscode_latex]{target=_blank}, [Java](../../guis/usage/ide_install.md#vscode),
+ which means you do not have to learn a new environment for your different projects.
+- Widespread use among the team:
+ Most developers of the OMC-Team use VSCode and are happy to help you with setting up and using it.
+
+### Recommended Extensions
+
+Main:
+
+- [Python][vscode_python_extension]{target=_blank}: [Documentation][vscode_python]{target=_blank}
+- [Jupyter][vscode_jupyter]{target=_blank}: [Documentation][vscode_interactive_python]{target=_blank}
+- [Remote SSH][vscode_remote_ssh_extension]{target=_blank}: [Documentation][vscode_remote_ssh]{target=_blank} and [lxplus SSH configuration][vscode_lxplus]{target=_blank .cern_login}.
+
+Additional:
+
+- [Ruff][vscode_ruff]{target=_blank}: A fast Python linter.
+- [Github Pull Requests][vscode_github]{target=_blank}: Interact with Github pull requests directly from VSCode.
+- [Markdown Table Formatter][vscode_markdown_tables]{target=_blank}: Format tables in markdown files.
+
+[vscode_lxplus]: https://cern.service-now.com/service-portal?id=kb_article&n=KB0008901
+[vscode_webpage]: https://code.visualstudio.com/
+[vscode_python]: https://code.visualstudio.com/docs/python/python-quick-start
+[vscode_debugging]: https://code.visualstudio.com/docs/python/debugging
+[vscode_interactive_python]: https://code.visualstudio.com/docs/python/jupyter-support-py
+[vscode_remote_ssh]: https://code.visualstudio.com/docs/remote/ssh-tutorial
+[vscode_testing]: https://code.visualstudio.com/docs/python/testing
+[vscode_marketplace]: https://marketplace.visualstudio.com/vscode
+[vscode_latex]: https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop
+[vscode_jupyter]: https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter
+[vscode_python_extension]: https://marketplace.visualstudio.com/items?itemName=ms-python.python
+[vscode_ruff]: https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
+[vscode_github]: https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github
+[vscode_markdown_tables]: https://marketplace.visualstudio.com/items?itemName=fcrespo82.markdown-table-formatter
+[vscode_remote_ssh_extension]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh
\ No newline at end of file
diff --git a/docs/packages/development/managing.md b/docs/packages/development/managing.md
new file mode 100644
index 00000000..f5820d35
--- /dev/null
+++ b/docs/packages/development/managing.md
@@ -0,0 +1,151 @@
+# Managing the Repositories
+
+While many people contribute to our code-bases, this page is for the elect few who are responsible for maintaining them.
+You will need access to the service accounts to make use of the information contained in this page.
+
+## Lintrack
+
+`lintrack` refers to the location of the codebase in the TN
+
+```bash
+/afs/cern.ch/eng/sl/lintrack/
+```
+
+as well as the service account handling the access to it.
+
+The service account was created as in the past direct access to these repositories lead to
+accidental changes that affected all users.
+Limiting access to the service account ensures an active decision to make modifications and thus avoids unwanted changes and binary or data loss,
+which can be especially troublesome if only detected online during CCC measurements.
+
+You can log into the `lintrack` account with the following command:
+
+```bash
+ssh lintrack@lxplus.cern.ch
+```
+
+You will then be greeted with a welcome message and some information about shortcuts we have set up for quick access and management of the repositories.
+
+!!! info "Access"
+ Due to CERN regulations, you cannot log into the `lintrack` account from outside the CERN network.
+
+### Repositories
+
+Local copies of the [github repositories][pylhc_github] are kept in `/afs/cern.ch/eng/sl/lintrack/omc_repos/`.
+There is a shortcut available on the `lintrack` welcome screen to update all repositories.
+
+These repositories are used in the `python_edge` environment and might be modified online to test new features
+or fix issues.
+
+!!! warning "Keeping them clean"
+ Changes to the repositories should be short lived and patched into the packages properly within a day or two and the repository reset to its original state.
+ In the past, changes made during shifts were often forgotten and after a while no one knew why the changes were made which version was the correct one to use.
+
+### Python Installations
+
+The python installations are located in `/afs/cern.ch/eng/sl/lintrack/omc_acc_py/`.
+In this folder you can also find the `acc-py` installers as well as the `omc_requirements_*.txt` files to easily setup new environments.
+
+- `/afs/cern.ch/eng/sl/lintrack/omc_acc_py/base/` contains the base `acc-py` installations from which the environments are derived.
+- In `/afs/cern.ch/eng/sl/lintrack/omc_acc_py/venv/` contains the environments. These are automatically picked up by the [BetaBeat GUI](../..//guis/betabeat/gui.md).
+
+The main environments are:
+
+- `omc_py3xx_releases`: The main production environment which is used for the CCC. All packages are installed via their official `pypi` release.
+- `omc_py3xx_repos`: The development environment which is used for the testing of new packages. All packages are installed from the local `git` repositories.
+
+These two environments are also symlinked to `/afs/cern.ch/eng/sl/lintrack/omc_python3` and `/afs/cern.ch/eng/sl/lintrack/omc_python_edge` respectively.
+
+!!! info "TODO"
+ - If you want the newest version of a repository to be used in `python_edge` you need to pull the changes into the local repository manually (see also the `lintrack` welcome screen).
+ - Whenever there is a new release for one of the packages, it needs to be manually installed into the `omc_py3xx_releases` environment.
+ Shortcuts are available (see the `lintrack` welcome screen), but for single updates one can use `python -m pip install -U
+ Check them sometimes for updates and try to keep their versions up-to-date!
+
+### pylhctokens
+
+This service account was originally created to give workflows access to the repos, until github introduced the automatically generated `GITHUB_TOKEN`.
+Nowadays we only use it to assign labels to all repositories.
+
+To log into the `pylhctokens` account you need password and 2FA authentication.
+
+### CODEOWNERS
+
+To avoid malicious or accidental changes to the repositories, the `master` branches are locked (Repo -> Settings -> Branch protection)
+and reviews are required before pull requests can be merged.
+
+The approved reviewers are handled via the `approved-reviewers` group in the `pylhc` organization's teams
+which are assigned as code owners to each repository.
+For that purpose, each repository has a `CODEOWNERS` file, which can be found in the `.github` folder of the repository.
+
+For more details, see the [official documentation][github_codeowners].
+
+## PyPI
+
+The access to [PyPI][pypi] is provided by the `pylhc` service account, for which you will need password and 2FA authentication.
+
+Publishing access is given to the github workflows via [API-Token][pypi_apitoken] (Settings -> Account Settings -> API Tokens) to all repositories of the `pylhc` organization.
+This is done by using the [publish workflow][pylhc_publish] and passing the token as secret:
+
+- `PYPI_USERNAME` : `__token__` (literal string)
+- `PYPI_PASSWORD` : the token value, including the pypi- prefix
+
+which are usually inherited from each of the repos publishing workflows.
+
+## Zenodo
+
+There is no special account for [Zenodo][zenodo] access.
+Zenodo should be able to be reached with your normal account, preferrably your `github`,
+which, if linked correctly, will allow Zenodo to also reach the `pylhc`-Organization repositories.
+
+To add a new repository to Zenodo, you need to make sure that the `.zenodo.json` file is correct (examples can be found in our repositories).
+**Before making your first release**, you need to go into the [Zenodo github settings][zenodo_github] (down-arrow on your user on the top right) and follow the instructions there:
+
+- Flip the switch to `On`
+- Create a release on `github` -> The page for your repo should now be visible on Zenodo!
+- Add the `badge` to your `README.md`
+
+[pypi]: https://pypi.org
+[zenodo]: https://zenodo.org
+[zenodo_github]: https://zenodo.org/account/settings/github/
+[pylhc_github]: https://github.com/pylhc
+[pylhc_github_github]: https://github.com/pylhc/.github
+[pylhc_publish]: https://github.com/pylhc/.github/blob/master/.github/workflows/publish.yml
+[pypi_apitoken]: https://pypi.org/help/#apitoken
+[pylhc_labels_workflow]: https://github.com/pylhc/.github/blob/master/.github/workflows/assign_labels_to_all_repos.yml
+[pylhc_labels_json]: https://github.com/pylhc/.github/blob/master/labels/labels.json
+[github_codeowners]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
\ No newline at end of file
diff --git a/docs/packages/irnl/about.md b/docs/packages/irnl/about.md
index 44058aa8..8d146e8f 100644
--- a/docs/packages/irnl/about.md
+++ b/docs/packages/irnl/about.md
@@ -2,7 +2,6 @@
[This package][repo] performs local correction of the Resonance Driving Terms (RDTs) in the Insertion Regions (IRs) based on the principle described in [^OBruning] with the addition of correcting feed-down and using feed-down to correct lower order RDTs. Details can be found in [^JDilly].
-
## Documentation
- [Autogenerated docs][documentation] via ``sphinx``.
@@ -20,10 +19,8 @@ After installing, codes can be run with either `python -m irnl-rdt-correction --
[repo]: https://github.com/pylhc/irnl_rdt_correction
[documentation]: https://pylhc.github.io/irnl_rdt_correction/
-
-
[^OBruning]:
- ??? abstract "Dynamic aperture studies for the LHC separation dipoles, `O. Bruning et al. `, [https://cds.cern.ch/record/742967](https://cds.cern.ch/record/742967){target=_blank}"
+ ??? abstract "Dynamic aperture studies for the LHC separation dipoles, `O. Bruning et al.`, [https://cds.cern.ch/record/742967](https://cds.cern.ch/record/742967){target=_blank}"
```
@techreport{Brüning:742967,
author = "Brüning, Oliver Sim and Fartoukh, Stéphane David and
diff --git a/docs/packages/mess/about.md b/docs/packages/mess/about.md
index df9a4928..56c379bf 100644
--- a/docs/packages/mess/about.md
+++ b/docs/packages/mess/about.md
@@ -5,20 +5,20 @@
!!! todo
Examples of are missing. Maybe just copy-paste of the `README.md` files in the repository.
-### Getting Started
+## Getting Started
The scripts can be browsed via github or the full repository can be obtained either via `git clone https://github.com/pylhc/MESS.git` or downloading the zipped repository.
-### Prerequisites
+## Prerequisites
To run the scripts, [MAD-X][madx] is required. If not otherwise stated, all scripts have been tested using MAD-X > 5.05.02.
-### Documentation
+## Documentation
- Each script directory contains a ``README``, outlining the basic functionality and notes on possible pitfalls.
- Excessive use of comments in the MAD-X scripts itself is encouraged.
-### Maintainability
+## Maintainability
- The main scripts should be named ``job.madx`` and placed in an accordingly named directory in the directory tree.
- Supporting files should be uploaded in the script directory. Links to external afs directories should be avoided as files might be modified there or removed.
@@ -40,7 +40,7 @@ To run the scripts, [MAD-X][madx] is required. If not otherwise stated, all scri
## Authors
-* **pyLHC/OMC-Team** - *Working Group* - [pyLHC][omc_team]
+- **pyLHC/OMC-Team** - *Working Group* - [pyLHC][omc_team]
## License
@@ -49,4 +49,4 @@ This project is licensed under the MIT License - see the [LICENSE][license] file
[repo]: https://github.com/pylhc/MESS
[madx]: https://mad.web.cern.ch/mad/
[omc_team]: https://github.com/orgs/pylhc/teams/omc-team
-[license]: https://github.com/pylhc/MESS/blob/master/LICENSE
\ No newline at end of file
+[license]: https://github.com/pylhc/MESS/blob/master/LICENSE
diff --git a/docs/packages/omc3/about.md b/docs/packages/omc3/about.md
index ff584889..85cdeab4 100644
--- a/docs/packages/omc3/about.md
+++ b/docs/packages/omc3/about.md
@@ -9,13 +9,15 @@ The `omc3` repository is the new version of our codes, refactored and rewritten
## Installing
-Installation is easily done via pip:
+Installation is easily done via `pip`:
+
```bash
python -m pip install omc3
```
Additionally, some features require access to the CERN Technical Network and require CERN-specific dependencies.
Those are installable from the CERN `Acc-Py` index through the `cern` extra, and can be installed from the CERN network or by providing the `index-url`:
+
```bash
python -m pip install --index-url http://acc-py-repo.cern.ch:8081/repository/vr-py-releases/simple --trusted-host acc-py-repo.cern.ch "omc3[cern]"
```
diff --git a/docs/packages/omc3/analysis.md b/docs/packages/omc3/analysis.md
index 8083998e..0ccabef4 100644
--- a/docs/packages/omc3/analysis.md
+++ b/docs/packages/omc3/analysis.md
@@ -20,7 +20,7 @@ The table below shows a general analysis workflow from BPM turn-by-turn measurem
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.
In this walk-through, we will cover the use of the different entrypoints available to perform necessary steps.
-!!! example
+!!! example
For our walk-through example, we will start from data obtained in `MAD-X` with the `TRACK` command for the 1023 turns in the LHC machine, with a scenario adapted from the 2018 configuration.
Changes from the nominal scenario in your simulation could be including errors tables, orbit bumps, speculative magnet errors, additional elements etc.
It is also easy for the reader to follow along if starting from measurements files.
@@ -29,16 +29,16 @@ In this walk-through, we will cover the use of the different entrypoints availab
Here is the `MAD-X` script that will generate the example data used in this walk-through.
It sets up a simple LHC configuration using files from `afs`, performs tracking and outputs a file named `trackone`.
The script can be copy-pasted with a click in the top right of its box.
-
+
For anyone without access to `afs`, you can find these files in our [MESS][mess] repository, or can simply use one of your own.
```fortran
option, warn, info;
option, echo=false, warn=false;
-
+
! ----- Set up Lattice and Define the Optics ----- !
call, file="/afs/cern.ch/eng/lhc/optics/runII/2018/lhc_as-built.seq"; ! needs AFS access
call, file="/afs/cern.ch/eng/lhc/optics/runII/2018/PROTON/opticsfile.22"; ! needs AFS access
-
+
! ----- Re-Cycle Sequence as in the Model ----- !
seqedit, sequence=lhcb1;
flatten;
@@ -49,10 +49,10 @@ In this walk-through, we will cover the use of the different entrypoints availab
beam, sequence=lhcb1, particle=proton, bv=1, energy=6500, npart=1e10, ex=5.4115e-10, ey=5.4115e-10;
beam, sequence=lhcb2, particle=proton, bv=-1, energy=6500, npart=1e10, ex=5.4115e-10, ey=5.4115e-10;
use, sequence=lhcb1;
-
+
! ----- Introduce Some Coupling ----- !
CMRS.b1_sq = 0.001;
-
+
! ----- Match Tunes and Chromaticities ----- !
match, chrom=true;
global, sequence=lhcb1, q1=62.31, q2=60.32, dq1=2.0, dq2=2.0;
@@ -62,13 +62,13 @@ In this walk-through, we will cover the use of the different entrypoints availab
vary, name="dqpy.b1_sq", step=1e-07;
lmdif, calls=100, tolerance=1e-21;
endmatch;
-
+
! ----- Slice Lattice for Tracking ----- !
- slicefactor = 4;
+ slicefactor = 4;
call, file="/afs/cern.ch/eng/lhc/optics/runII/2018/toolkit/myslice.madx"; ! needs AFS access
use, sequence=lhcb1;
makethin, sequence=lhcb1, style=teapot, makedipedge=false;
-
+
! ----- Define Observation Points and Perform Tracking ----- !
! These points are the BPMs from the model's twiss.dat file
use, sequence=lhcb1;
@@ -650,6 +650,7 @@ The formats supported by the converter are:
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:
+
```bash
python -m omc3.tbt_converter \
--files trackone \
@@ -679,10 +680,10 @@ For this, `omc3` provides the `model_creator` entrypoint, which allows you to ru
The out-of-the-box supported machines for model creation are `lhc`, `ps` and `psbooster`, machines we work on.
While the `skekb`, `JPARC`, `petra` and `iota` have accelerator classes, no model creator has been implemented for them yet.
It is possible to extend this list for your machine by defining an appropriate `Accelerator` class as well as a model creator.
- See [this guide][new_machine_guide] for implementation steps.
-In our example, we would like to compare our data to the nominal model of the 2018 LHC.
+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:
+
```bash
python -m omc3.model_creator \
--accel lhc \
@@ -700,30 +701,32 @@ Refer to the [model creator's API documentation][model_creator] for the list of
The model creation runs a `MAD-X` scenario and outputs the relevant twiss results to the desired directory.
Running `ls lhc_model/` yields:
+
```bash
-b2_errors.tfs error_deffs.txt macros twiss_elements.dat
-b2_settings.madx job.create_model.madx twiss.dat
+b2_errors.tfs error_deffs.txt macros twiss_elements.dat
+b2_settings.madx job.create_model.madx twiss.dat
```
!!! question "What is a Model?"
As one can see, a "model" is essentially one or more TFS files with optics functions at BPMs (`twiss.dat`) and elements (`twiss_elements.dat`), other files being here for the user to understand or reproduce the result.
Had we created a driven model, then an additional `twiss_ac.dat` or `twiss_adt.dat` file would have been created, with optics functions at BPMs while driving the beam.
- One can create their own models without the `model_creator` should they want to, as it only acts as a convenience wrapper.
+ One can create their own models without the `model_creator` should they want to, as it only acts as a convenience wrapper.
A `driven model` is the same as above, with also a `TWISS` taking into account the exciting effect of an AC dipole or ADT onto the optics.
- Creating this is easiest done with the `model_creator`, but can also be done individually with the a script installing the appropriate element into your sequence.
+ Creating this is easiest done with the `model_creator`, but can also be done individually with the a script installing the appropriate element into your sequence.
## 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.
+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][hole_in_one].
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:
+
```bash
python -m omc3.hole_in_one --harpy \
--files trackone.sdds \
@@ -748,16 +751,17 @@ The filenames are determined by appending the appropriate suffixes to the entry
!!! info "Bad BPMs"
If given `bpm_summary` for the `--to_write` flag (which is the case by default), `harpy` will output the `.bad_bpms_[xy]` files.
BPMs are determined as bad or not depending on several options from the cleaning phase.
- While these are given sensible defaults, one might need to tweak them manually depending on their measurement.
+ While these are given sensible defaults, one might need to tweak them manually depending on their measurement.
Additionally, known bad BPMs can be given with the `--bad_bpms` flag.
In the output files, various properties are given in column form for each observation point.
Running `ls harpy_output/` yields the following result:
+
```bash
-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
+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
```
!!! tip "Plotting the Spectra"
@@ -779,7 +783,7 @@ trackone.sdds.bad_bpms_y trackone.sdds.liny
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.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))
@@ -788,7 +792,7 @@ trackone.sdds.bad_bpms_y trackone.sdds.liny
The `*.lin[xy]` files contain various data (in columns) computed for each BPM (in rows) as some summary information.
Some column names are explicit: `BPM_RES` contains the determined BPM resolution, `CO` the closed orbit value at said BPM and `PK2PK` is the peak-to-peak value of oscillations registered by the given BPM.
`TUNE[XY]`, `AMP[XY]` and `MU[XY]` are the detected tune, the amplitude of the tune line and the phase of the tune line for said BPM, respectively.
-
+
The other columns describe the phase (`PHASE`), amplitude ratio (`AMP`) and frequency (`FREQ`) of the line identified by the number in the column name, where underscores represent a minus sign.
Therefore, in the `.linx` file `FREQ01`, `AMP01` and `PHASE01` are respectively the frequency of the main vertical tune line in the horizontal spectrum, the ratio of this line's amplitude to that of the main horizontal line and the phase of this line.
The equivalent columns in the `.liny` file are `FREQ10`, `AMP10` and `PHASE10`.
@@ -803,6 +807,7 @@ To do so, `omc3` provides the `hole_in_one` entrypoint, to be used this time wit
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` requires providing an error definition file which our simulation did not implement.
Calling the entrypoint to perform optics analysis goes as:
+
```bash
python -m omc3.hole_in_one --optics \
--accel lhc \
@@ -826,13 +831,14 @@ To use these, refer to the `Optics Kwargs` section of the [hole_in_one API docum
In the output files, various properties are given in column form for each observation point.
Running `ls measured_optics/` yields the following result:
+
```bash
-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
+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
```
---
@@ -841,7 +847,7 @@ interaction_point_y.tfs phase_x.tfs
The harmonic analysis and optics analysis don't necessarily have to be separated steps.
It is possible to run the `hole_in_one` entrypoint with both `--harpy` and `--optics` flags, even though the command might become cumbersome.
The associated flags and options do not change, although only one `outputdir` should be given.
-
+
Our example done in one step would be:
```bash
python -m omc3.hole_in_one --harpy --optics \
@@ -862,11 +868,15 @@ interaction_point_y.tfs phase_x.tfs
In this case, the output files from `harpy` are automatically handled and put into a subfolder named `lin_files` inside of the specified `outputdir`.
The rest is done and output as seen above.
+## 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](../../measurements/procedures/ampdet.md#analysis).
+
[mess]: https://github.com/pylhc/MESS
[sdds]: https://ops.aps.anl.gov/SDDSIntroTalk/slides.html
[tbt_converter]: https://pylhc.github.io/omc3/entrypoints/other.html#tbt-converter
[plot_spectrum]: https://pylhc.github.io/omc3/entrypoints/plotting.html#plot-spectrum
[normal_forms]: https://cds.cern.ch/record/333077/files/p93.pdf
[hole_in_one]: https://pylhc.github.io/omc3/entrypoints/analysis.html#omc3.hole_in_one.hole_in_one_entrypoint
-[new_machine_guide]: know_how.md#how-to-create-files-for-your-file-accelerator
[model_creator]: https://pylhc.github.io/omc3/entrypoints/other.html#model-creator
diff --git a/docs/packages/omc3/getting_started.md b/docs/packages/omc3/getting_started.md
index c90a613c..a794dba4 100644
--- a/docs/packages/omc3/getting_started.md
+++ b/docs/packages/omc3/getting_started.md
@@ -3,24 +3,24 @@
## Quick start
The `omc3` package is `Python 3.7+` compatible, but not yet deployed to PyPI.
-The best way to install is though pip and VCS:
+The best way to install is though python -m pip and VCS:
```bash
git clone https://github.com/pylhc/omc3
-pip install /path/to/omc3
+python -m pip install /path/to/omc3
```
Or simply from the online master branch, which is stable:
```bash
-pip install git+https://github.com/pylhc/omc3.git
+python -m pip install git+https://github.com/pylhc/omc3.git
```
After installing, codes can be run with either `python -m omc3.SCRIPT --FLAG ARGUMENT` or calling path to the `.py` file directly.
## Functionality
-#### Main Scripts
+### Main Scripts
Main scripts to be executed lie in the `/omc3` module directly. These include:
@@ -31,7 +31,7 @@ Main scripts to be executed lie in the `/omc3` module directly. These include:
- `tbt_converter.py` to convert different turn by turn datatypes to sdds, and add noise.
- `amplitude_detuning_analysis.py` to perform amp. det. analysis on optics data with tune correction.
-#### Plotting Scripts
+### Plotting Scripts
Plotting scripts for analysis outputs can be found in the `/omc3/plotting` submodule:
@@ -41,7 +41,7 @@ Plotting scripts for analysis outputs can be found in the `/omc3/plotting` submo
- `plot_optics_measurements.py` to generate plots from files generated by optics_measurements.
- `plot_tfs.py` all purpose tfs-file plotter.
-#### Other Scripts
+### Other Scripts
Other general utility scripts are in `/omc3/scripts` module:
@@ -49,4 +49,4 @@ Other general utility scripts are in `/omc3/scripts` module:
- `write_madx_macros.py` to generate `MAD-X` tracking macros with observation points from a twiss file.
- `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.
-A typical analysis workflow with `omc3` is described in the [next page](analysis.md).
\ No newline at end of file
+A typical analysis workflow with `omc3` is described in the [next page](analysis.md).
diff --git a/docs/packages/omc3/know_how.md b/docs/packages/omc3/know_how.md
deleted file mode 100644
index c1e18094..00000000
--- a/docs/packages/omc3/know_how.md
+++ /dev/null
@@ -1,10 +0,0 @@
-## How to create files for your file accelerator
-
-TODO: write a little howto about what should be written for a user wanting to add their own accelerator.
-
-## Drive vs Harpy
-
-TODO: gather here the differences between the two (factors, normalization etc).
-
-!!! note
- Knowledge about `omc3` details and ways to do things. Should include info on all functionality, plus answers to things we mention in meetings or Mattermost.
diff --git a/docs/packages/pylhc/about.md b/docs/packages/pylhc/about.md
index 86cac24e..a5aa2f59 100644
--- a/docs/packages/pylhc/about.md
+++ b/docs/packages/pylhc/about.md
@@ -27,6 +27,7 @@ After installing, codes can be run with either `python -m pylhc.SCRIPT --FLAG AR
Note: similarly to `omc3`, some of the scripts access functionality only available on the CERN Technical Network.
To use those, you should make sure to install the relevant extra dependencies with:
+
```bash
python -m pip install --index-url http://acc-py-repo.cern.ch:8081/repository/vr-py-releases/simple --trusted-host acc-py-repo.cern.ch "pylhc[cern]"`.
```
diff --git a/docs/packages/pylhc/bpm_calibration.md b/docs/packages/pylhc/bpm_calibration.md
index 5f351bd4..472e1225 100644
--- a/docs/packages/pylhc/bpm_calibration.md
+++ b/docs/packages/pylhc/bpm_calibration.md
@@ -3,7 +3,8 @@
The `bpm_calibration` module of `PyLHC` can be used to compute [BPM calibration factors][bpm_calibration].
Only one entrypoints exists for both methods, the argument `method` can be used to select it, and defaults to `beta`.
Using the script to make compute calibration factors through $\beta$-functions for instance from IP1 and IP5 goes as:
-```bash
+
+```bash
python -m pylhc.bpm_calibration \
--input