From cc3b3c361b42cda5c698066e15add28d80cd5e2a Mon Sep 17 00:00:00 2001
From: Alexis Gamelin <alexis.gamelin@synchrotron-soleil.fr>
Date: Tue, 17 Oct 2023 14:44:25 +0200
Subject: [PATCH] Docstring improvements
Improve ProportionalIntegralLoop & DirectFeedback docstrings.
---
mbtrack2/tracking/rf.py | 41 +++++++++++++++++++++--------------------
1 file changed, 21 insertions(+), 20 deletions(-)
diff --git a/mbtrack2/tracking/rf.py b/mbtrack2/tracking/rf.py
index 0e4287e..36fa232 100644
--- a/mbtrack2/tracking/rf.py
+++ b/mbtrack2/tracking/rf.py
@@ -1106,28 +1106,30 @@ class ProportionalIntegralLoop():
cav_res : CavityResonator object
CavityResonator in which the loop will be added.
gain : float list
- Proportional gain (Pgain) and integral gain (Igain) of the feedback system.
+ Proportional gain (Pgain) and integral gain (Igain) of the feedback
+ system in the form of a list [Pgain, Igain].
For IQ feedback, same gain set is used for I and Q.
- In case of normal conducting cavity (QL~1e4),
- the Pgain of ~1.0 and Igain of ~1e4(5) are usually used.
- In case of super conducting cavity (QL > 1e6),
- the Pgain of ~100 can be used.
- In a "bad" parameter set, unstable oscillation of Vc is caused.
- So, parameter scan of Vcloop should be made.
+ In case of normal conducting cavity (QL~1e4), the Pgain of ~1.0 and
+ Igain of ~1e4(5) are usually used.
+ In case of super conducting cavity (QL > 1e6), the Pgain of ~100
+ can be used.
+ In a "bad" parameter set, unstable oscillation of the cavity voltage
+ can be caused. So, a parameter scan of the gain should be made.
sample_num : int
- Sample number to monitor Vc
- The averaged Vc value in sample_num is monitored.
+ Number of bunch over which the mean cavity voltage is computed.
Units are in bucket numbers.
every : int
- Interval to monitor and change Vc
+ Time interval between two cavity voltage monitoring and feedback.
Units are in bucket numbers.
delay : int
Loop delay of the PI feedback system.
Units are in bucket numbers.
FF : bool, optional
Boolean switch to use feedforward constant.
- True is recommended to prevent a Vc drop in the beginning of the tracking.
- In case of small Pgain (QL ~ 1e4), Vc drop may cause beam loss due to static Robinson.
+ True is recommended to prevent a cavity voltage drop in the beginning
+ of the tracking.
+ In case of small Pgain (QL ~ 1e4), cavity voltage drop may cause
+ beam loss due to static Robinson.
Default is True.
Methods
@@ -1149,14 +1151,14 @@ class ProportionalIntegralLoop():
-----
Assumption : delay >> every ~ sample_num
- Adjusting ig(Vg) parameter to keep the Vc constant (to target(Vref) values).
+ Adjusting ig(Vg) parameter to keep the cavity voltage constant (to target values).
The "track" method is
- 1) Monitoring the Vc phasor
- Mean Vc value between specified bunch number (sample_num) is monitored
+ 1) Monitoring the cavity voltage phasor
+ Mean cavity voltage value between specified bunch number (sample_num) is monitored
with specified interval period (every).
2) Changing the ig phasor
The ig phasor is changed according the difference of the specified
- reference values (Vref) with specified gain (gain).
+ reference values with specified gain (gain).
By using ig instead of Vg, the cavity response can be taken account.
3) ig changes are reflected to Vg after the specifed delay (delay) of the system
@@ -1196,7 +1198,7 @@ class ProportionalIntegralLoop():
self.every = 1
record_size = int(np.ceil(self.delay/self.every))
if record_size < 1:
- raise ValueError("Bad parameter set : delay or sample_every")
+ raise ValueError("Bad parameter set : delay or every")
self.sample_num = int(sample_num)
# init lists for FB process
@@ -1385,7 +1387,7 @@ class DirectFeedback(ProportionalIntegralLoop):
record_size = int(np.ceil(self.DFB_delay/self.DFB_every))
if record_size < 1:
- raise ValueError("Bad parameter set : delay or sample_every")
+ raise ValueError("Bad parameter set : DFB_delay or DFB_every")
self.DFB_parameter_set(DFB_gain, DFB_phase_shift)
if np.sum(np.abs(self.cav_res.beam_phasor)) == 0:
@@ -1478,8 +1480,7 @@ class DirectFeedback(ProportionalIntegralLoop):
self.DFB_ig_phasor = self.Vg2Ig(vg_drf)
self.ig_phasor = self.ig_phasor_record - self.DFB_ig_phasor
- if self.FF:
- self.FFconst = np.mean(self.ig_phasor)
+ self.init_FFconst()
def track(self):
"""
--
GitLab