You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/guis/betabeat/settings.md
+217-7Lines changed: 217 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -3,19 +3,43 @@
3
3
<figure>
4
4
<center>
5
5
<imgsrc="../../assets/images/betabeat_gui/top_buttons.png"width="100%"alt="Icons at the top of the GUI." />
6
-
<figcaption>Open the settings window with the gear icon.</figcaption>
6
+
<figcaption>Open the settings window with the white-on-blue gear icon <spanclass="settings-icon">⚙</span>.</figcaption>
7
7
</center>
8
8
</figure>
9
9
10
10
Great care has been taken to create a user friendly and easy to find interface for all settings.
11
-
The settings window can be initialized by the gear icon in the top left corner of the GUI.
11
+
The settings window can be initialized by the gear icon <spanclass="settings-icon">⚙</span> in the top left corner of the GUI.
12
12
13
-
* Settings are now all in one place (the settings-button on top).
14
-
* Entries in the settings that are lists (e.g. 'Turns' which will be `STARTTURN ENDTURN`) are given as **space-separated** values, NOT comma separated.
15
-
* Settings can be reverted as long as you do not click apply.
16
-
* Settings are applied automatically on ++okbtn++.
17
-
* Settings are reset to last applied on ++cancelbtn++.
13
+
!!! info "Defaults"
14
+
The "Default" values given here are the defaults used in `python`,
15
+
These might not be up-to-date, check the [omc3 python documentation][python-docs]{:target="_blank"} for more information.
16
+
They might also be different from the defaults used in the GUI, as there are some defaults set upon startup determined by the selected machine.
17
+
These GUI defaults are directly visible in the settings, while the `python` defaults are used when no value is given.
18
18
19
+
## General Behaviour
20
+
21
+
There is some general behaviour, that is true for all settings-tabs:
22
+
23
+
-**Empty** text-fields are treated as _"Not given"_ and the **`python` defaults** will be used.
24
+
-**Hovering the mouse over the label** of a setting will give additional information.
25
+
This is often the `help` provided by the corresponding `python` argument. Check the [omc3 python documentation][python-docs]{:target="_blank"} for more information.
26
+
- Entries in the settings that are lists (e.g. _Turns_, which will be `STARTTURN ENDTURN`) are given as **space-separated** values, NOT comma separated.
27
+
- Of the buttons at the bottom, the top row refers to the current tab, the bottom row to all tabs.
28
+
- Settings that have been changed since the last ++"Apply"++ / ++"Apply All"++ are <spanstyle="color: red">highlighted in red</span> and can be reverted with the ++"Reset"++ button.
29
+
- Settings are applied **automatically** on ++okbtn++.
30
+
- Settings are **reset** to last applied on ++cancelbtn++.
31
+
- ++"Save to File"++: When saving the settings to file, a file `settings_xxx.properties` is created, containing entries for **ALL** settings, even those not set in the GUI.
32
+
- ++"Load from File"++: When loading settings from file, not all possible entries need to be present in that file and **only present ones will be modified** in the UI.
33
+
Entries in the file, that are not recognized as settings will be ignored.
34
+
35
+
36
+
!!! info "Some Background on the Internals"
37
+
To "apply" settings simply means that the current values in the UI are assinged to the corresponding settings class,
38
+
each an internal representation of a settings tab,
39
+
which is used to persistently store the settings in memory and pass them between different parts of the application.
40
+
To "reset" the settings, the stored values are reloaded from this internal representation to the UI.
41
+
42
+
## Gui-Tab
19
43
20
44
<figure>
21
45
<center>
@@ -24,34 +48,216 @@ The settings window can be initialized by the gear icon in the top left corner o
24
48
</center>
25
49
</figure>
26
50
51
+
The GUI tab contains settings that steer the behaviour of the GUI.
52
+
This is in contrasts to the other settings tabs, which control the settings passed on to the `python` tasks.
53
+
54
+
-**Turn-by-Turn Datatype of Files to be Opened**:
55
+
Specify the datatype of the turn-by-turn data files that you open when clicking on ++"Open Files"++{.green-gui-button} in the [BPM Panel](bpm_panel.md).
56
+
If you do **not** convert the files, this needs to be one of **`lhc`** or **`sps`**, as these are the only ones the GUI can handle.
57
+
58
+
-**Convert Turn-by-Turn Files on Opening**:
59
+
When **`Do not convert`** is selected, turn-by-turn files are simply copied into the current `Measurements` directory.
60
+
If **`lhc`** or **`sps`** is selected, the `omc3.tbt_converter` will be called to convert the files from the
61
+
datatype in the previous setting to the here selected type, **even if the same format is selected!**<br>
62
+
:fontawesome-solid-triangle-exclamation:{.warning-colored} _The copied/converted files are the ones that will be passed on to `harpy` later on.
63
+
As the default input format there is **`lhc`**, make sure to change it there in case you are using anything else!_
64
+
65
+
-**Phase-Advance as X-Axis in Optics-Tab**:
66
+
Uses the phase-advance (`MUX`/`MUY`) column as the X-Axis in the Optics-Tab instead of the longitudinal position (`S`).
67
+
68
+
-**Rename Optics-Dir on Import**:
69
+
If active and you open an already analysed optics directory, via the ++"Open Files"++{.green-gui-button} in the [Optics Panel](optics_panel.md),
70
+
which is **NOT** already in the current `Results` directory, the imported directory will be prefixed with the current time (as was default in the [BetaBeat.src version](betabeatsource.md)).
71
+
72
+
-**Analyse TbT Files on Opening**:
73
+
If active and you open a turn-by-turn file, via the ++"Open Files"++{.green-gui-button} in the [BPM Panel](bpm_panel.md),
74
+
`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).
75
+
76
+
-**Python Path**:
77
+
Change the location of the `python` executable to be used to run the python scripts.
78
+
After a change here, the GUI will check which versions of `omc3` and `pylhc` are installed in the selected environment and update the [entry at the top](common_components.md#top-of-the-gui).
79
+
80
+
-**Python Debugging**:
81
+
If active, the GUI will run the `python` script with the `-d` flag, which initializes the logging level in our scripts automatically to `DEBUG`.
82
+
83
+
-**Use Server for Analysis**:
84
+
When set, all `python` tasks requireing lots of memory and processing power (e.g. `hole-in-one` for `harpy` and `optics`) will be run on that server.
85
+
If you click the ++"Test"++ button, file creation and reading of the created files from the local machine will be tested and you will be prompted with the results after a few seconds.
86
+
87
+
-**Always use Server**:
88
+
If active, all `python` tasks will be run on the server, even if they do not require much processing power.
89
+
90
+
-**Run Per-File Tasks in Parallel**:
91
+
If active, tasks that are started together but can run independently per file will be run in individual tasks in parallel,
92
+
e.g. the `harpy` analysis will be run in parallel for each turn-by-turn file, even if started with multiple files selected.
93
+
Also, when running multiple optics analysis, but clicking the `Run per file` button, the analysis will be run in parallel for each file.
94
+
Conversely, if `Also run optics analysis` is selected, the first step of the `harpy` analsysis will be run sequentially per file,
95
+
as coordination between multiple tasks is not implemented.
<figcaption>The Tunes-tab of the settings window.</figcaption>
31
104
</center>
32
105
</figure>
33
106
107
+
In this tab, the settings for the tunes are defined.
108
+
The connection of these settings to the `python` settings is a bit tricky,
109
+
because some of the information is passed on to the input arguments of the `accelerator class` (the actual tunes) and some to `harpy` (the settings below).
110
+
111
+
### Tunes
112
+
113
+
In this grid, the horizontal (`X`), vertical (`Y`) and longitudinal (`Z`) tunes are defined.
114
+
In case of standard (i.e. 2D) kicks, the longitudinal tune needs to be set to `0`.
115
+
116
+
The tunes are automatically updated when [loading a model](model_creation.md), but can be manually adjusted.
117
+
118
+
The first row defines the main line to be found in the spectrum, which is the **driven tune** in the case of AC-Dipole kicks and
119
+
the **natural tune** in the case of free kicks.
120
+
121
+
The natural tunes can be given either directly or as differences to the main tune, by activating the `Nat. Deltas` checkbox.
122
+
This is also reflected in parameters given to `harpy` and can be useful together with the `Autotunes` setting, e.g. if different working points with the same delta a probed.
123
+
124
+
!!! warning "Deltas Sign-Convention"
125
+
The signs between the `Nat. Deltas` here and in [Multiturn][multiturn] are inverted, because [Multiturn][multiturn] uses the natural tunes as the basis
126
+
from which the AC-Dipole is set while `harpy` uses the highest peak in the spectrum (i.e. the AC-Dipole tune line) as the basis from which the natural tunes are found.
127
+
128
+
The ++"<-- Model"++ button will load the tunes of the respective row from the currently loaded model,
129
+
while the other buttons calculate the tune in the respective row from the other two rows.
130
+
++"Get all from Model"++ will load the tunes of all rows from the loaded model.
131
+
132
+
The fields are non-editable when it does not make sense in the current settings (e.g. no natural tunes when free kicks are used, switching between natural tunes and deltas).
133
+
**"Make all tune-fields editable"** overrides this and does exactly what it says.
134
+
135
+
### Settings
136
+
137
+
-**Free Kick**:
138
+
If active, free kicks are used instead of AC-Dipole kicks.
139
+
140
+
-**Autotunes**:
141
+
If active, the highest peak in the whole spectrum is automatically assumed to be the main tune, either in the **`transversal`** planes or in **`all`** planes including the longitudinal.
142
+
Otherwise the main tune is defined as the highest peak in the spectrum around the tunes given in the first row ± the tolerance.
143
+
144
+
-**Clean Limit**:
145
+
When cleaning is active, BPM outliers are detemined as those that are further away than others from the average.
146
+
This limit sets a hard border to the cleaning, where **outliers closer than the given limit to the average tune will not be removed**.
147
+
148
+
-**Tolerance**:
149
+
The tolerance for the peak search in the spectrum.
150
+
This tolerance is uses for all peaks (unless `Autotunes` is active, in which case it is not used for the main tune), i.e. for all harmonics/resonance lines searched for in the spectrum.
<figcaption>The Harpy-tab of the settings window.</figcaption>
38
159
</center>
39
160
</figure>
40
161
162
+
The Harpy-tab contains the settings for the harmonic `harpy` analysis.
163
+
164
+
-**Files**:
165
+
This field is not editable and automatically set when selecting TbT files in the [BPM Panel](bpm_panel.md) and running the analysis.
166
+
It is only shown here, as `files`is an argument to `harpy` and an attribute on the internal `HarpySettings` class, which is set later from the user selection.
167
+
168
+
-**Outputdir**:
169
+
This field is not editable and automatically set when running the harmonic analysis, as the selected file-names are used to define the output directory.
170
+
When running analysis from the GUI, the output files are put into the same directory as the input files,
171
+
unless also the optics-analysis is run at the same time, in which case they will be put in a sub-directory (`linfiles`) of the
172
+
respective optics output in the `Results` directory.
173
+
The field is only shown here, as `outputdir` is an argument to `harpy` and an attribute on the internal `HarpySettings` class, which is set later from the user selection.
174
+
175
+
-**Model**:
176
+
This field is not editable and automatically set when loading a model.
177
+
It contains the path to the `twiss.dat` file of the loaded model.
178
+
The field is only shown here, as `model` is an argument to `harpy` and an attribute on the internal `HarpySettings` class, which is usually already set.
179
+
180
+
-**Turns**:
181
+
Start and end turn to be used from the turn-by-turn data. Default: `[0, 50000]`.
182
+
- The order does not matter.
183
+
- If one argument is negative or zero, the very first turn is included.
184
+
- If the larger argument is larger than the number of turns, the last turn is included.
185
+
- If both arguments are higher than the number of turns, there will be an error.
186
+
- If the larger argument is also negative, these turns will be removed from the end.
187
+
- If both arguments are inside the range of turns, the turn of the larger argument will be the first one excluded (i.e. how `python` slices a list `[start:end]`).
188
+
189
+
-**Window**:
190
+
The type of windowing function used for the harmonic analysis, to create a closed-form of the signal.
191
+
Default: `hann`.
192
+
193
+
-**TurnBits**:
194
+
The number of bits to be used for zero-padding of the turn-by-turn data, which therefore defines the (interpolated) frequency resolution.
195
+
Here, the number of bits is the log of the number of turns in the data, i.e. `turn_bits = log2(turns)` or `turns = 2**turn_bits`, where `turns` is the number of measured turns + zero padding.
196
+
This also determines the memory footprint of the analysis and should be reduced for computers with low RAM.<br>
197
+
:fontawesome-solid-triangle-exclamation:{.warning-colored} Note, that for `6600` turns of measurement data, this number should not be set lower than `13`!<br>
198
+
Default: `20`.
199
+
200
+
-**OutputBits**:
201
+
The number of bits to be used for binning of the output data, i.e. `number_of_bins = 2**output_bits`.
202
+
This determines the final resolution of the frequency spectrum and the size of the output files.
203
+
Within each bin, only the highest peak is kept, leading to uneven frequency distribution.
204
+
Default: `12`.
205
+
206
+
-**Write Out**:
207
+
This parameter determines which output files are written out.
208
+
Each file has usually a `x` and `y` version for each per plane.
209
+
The following options are available:
210
+
-`lin`: Write out the `.lin`-file, which contain a table of BPMs and summarize their main and resonance lines, as well as additional information, e.g. noise.
211
+
-`spectra`: Write out the `.amps` and `.freqs`-files, which contain the amplitudes and frequencies within the given `Tolerance` (see [Tunes Tab](#tunes-tab)) around the main and resonance lines.
212
+
-`full_spectra`: This setting overrides the `spectra`-setting and writes out **all** amplitudes and frequencies of the binned spectrum in the same file-format.
213
+
-`bpm_summary`: Write out the `.bad_bpms`-file, which contains a summary of BPMs that are determined as bad or not.
214
+
215
+
-**Unit**:
216
+
The unit of the input turn-by-turn data.
217
+
Default: `m`.<br>
218
+
:fontawesome-solid-triangle-exclamation:{.warning-colored} This unit is only valid for the **input data**, internally and in the output files `m` are used.<br>
219
+
:fontawesome-solid-triangle-exclamation:{.warning-colored} The units for measured LHC turn-by-turn files are `mm`.<br>
220
+
221
+
-**TbtDataType**:
222
+
The datatype of the input turn-by-turn data.
223
+
Many options are available here, as they could be used when running the analysis from commadline.
224
+
Yet, as we have imported the data already into the GUI, and the GUI only supports `lhc` and `sps` turn-by-turn data, this setting should be set to either of these two values.
225
+
Default: `lhc`.
226
+
227
+
-**Resonances**:
228
+
The multipole order of the resonances looked for in the spectrum and written out in the `lin`-files.
229
+
If you want to run optics analysis for high-order RDTs later on, you need to set this number respectively, depending on the order of the RDT you want to analyse.
230
+
Default: `4`.
231
+
232
+
### Automated Suffixes
233
+
234
+
The harmonic analysis accepts a `suffix` parameter as input, to distinguish between different analysis runs, e.g. with various parameter settings, on the same file.
235
+
The _"Automated Suffixes"_ feature of the GUI creates this suffix automatically using the values of the here selected parameters, allowing you to easily compare the impact of different settings on the same data.
236
+
This uses not only parameters from this tab but also from the [cleaning-tab](#cleaning-tab) and [tunes-tab](#tunes-tab).
237
+
You can also define your own suffix, which will be added to the automatically created one.
0 commit comments