v1.15.0, see README.md for details.

Author: dquartul

README.md

@@ -4,7 +4,6 @@ copied verbatim in the file LICENCE.md.
 In applying this licence, CERN does not waive the privileges and immunities 
 granted to it by virtue of its status as an Intergovernmental Organization or
 submit itself to any jurisdiction.
-Project website: http://blond.web.cern.ch/
 
 CODE NAME
 =========
@@ -16,46 +15,59 @@ DESCRIPTION
 ===========
 
 CERN code for the simulation of 
-longitudinal beam dynamics with collective effects.
+longitudinal beam dynamics in synchrotrons.
 
 
 LINKS
 =====
 
 Repository:
-	https://gitlab.cern.ch/dquartul/BLonD
+	https://github.com/dquartul/BLonD
 
 Documentation:
-	http://blond-documentation.web.cern.ch/
-	
+	http://dquartul.github.io/BLonD/
+
 Project website:
 	http://blond.web.cern.ch
 
 
-DEVELOPERS
-==========
+CURRENT DEVELOPERS
+==================
 
+Simon Albright (simon.albright (at) cern.ch)
+Konstantinos Iliakis (konstantinos.iliakis (at) cern.ch)
 Alexandre Lasheen (alexandre.lasheen (at) cern.ch)
 Juan Esteban Muller (juan.fem (at) cern.ch)
 Danilo Quartullo (danilo.quartullo (at) cern.ch)
+Joel Repond (joel.repond (at) cern.ch)
 Helga Timko (Helga.Timko (at) cern.ch)
 
+PREVIOUS DEVELOPERS
+===================
+
+Theodoros Argyropoulos
+
 
 STRUCTURE
 ==========
 
 1) the folder __TEST_CASES contains several main files which
    show how to use the principal features of the code; 
-2) the __doc folder contains the source files for the documentation; 
+2) the __doc folder contains the source files for the documentation on-line; 
 3) the various packages which constitute the code;
-4) the setup_cpp and setup_cython files needed to compile the C++ and Cython
-   files present in the corresponding packages respectively; these files 
-   should be run once before launching any simulation. 
-   The compiler C/C++ GCC (at least version 4.8) is necessary.
+4) setup_cpp.py is needed to compile all the C++ files present in the project; 
+   this file should be run once before launching any simulation. 
+   The compiler C++ GCC (at least version 4.8) is necessary.
+5) WARNINGS.txt contains useful information related to code usage.
 
 
 VERSION CONTENTS 
 ================
+2016-06-23
+v1.14.5 - RF modulation file added in llrf folder
+        - documentation on-line for PSB phase loop added
+        - setup_cython.py removed because not used
+
 2016-06-21
 v1.14.4 - PSB phase loop and rf noise fixed
 

__doc/source/llrf.rst

@@ -388,19 +388,56 @@ Machine-dependent Beam Phase Loop
 
 
    .. py:method:: PSB():
-
-      Calculates the RF frequency correction :math:`\Delta \omega_{\mathsf{PL}}`
-      from the phase difference between beam and RF 
-      :math:`\Delta \varphi_{\mathsf{PL}}` for the PSB. The transfer function is
+      
+      Phase loop:
+      
+      The transfer function of the system is
 
-      .. math:: \Delta \omega_{\mathsf{PL}} = 2 \pi g 
-         \frac{a_0 \Delta \varphi_{\mathsf{PL}}^2 
-         + a_1 \Delta \varphi_{\mathsf{PL}} + a_2 }
-         {\Delta \varphi_{\mathsf{PL}}^2 
-         - b_1 \Delta \varphi_{\mathsf{PL}} - b_2} .
-            
-      Input :math:`g` through ``gain`` and the array 
-      :math:`[a_0, a_1, a_2, b_1, b_2]` through ``coefficients``.       
-
-
+      .. math:: H(z) = g \frac{b_{0}+b_{1} z^{-1}}{1 +a_{1} z^{-1}}  
+      
+      where g is the gain and :math:`b_{0} = 0.99901903`, :math:`b_{1} = -0.99901003`,  
+      :math:`a_{1} = -0.99803799`.
+      
+      Let :math:`\Delta \phi_{PL}` and :math:`\Delta \omega_{PL}` be the
+      phase difference and the phase loop correction on the frequency
+      respectively; since these two quantities are the input and output of our 
+      system, then from the transfer function we
+      have in time domain (see https://en.wikipedia.org/wiki/Z-transform):
+      
+      .. math:: \Delta \omega_{PL}^{n+1} = - a_{1} \Delta \omega_{PL}^{n} + 
+            g(b_{0} \Delta \phi_{PL}^{n+1} + b_{1} \Delta \phi_{PL}^{n})
+      
+      In fact the phase and radial loops act every 10 :math:`\mu s` and as a 
+      consequence :math:`\Delta \phi_{PL}` is an average on all the values 
+      between two trigger times.
+      
+      Radial loop:
+      
+      We estimate
+      the difference of the radii of the actual trajectory and the desired trajectory
+      using one of the four known differential relations with :math:`\Delta B = 0`:
+      
+      .. math:: \frac{\Delta R}{R} = \frac{\Delta \omega_{RF}}{\omega_{RF}} 
+        \frac{\gamma^2}{\gamma_{T}^2-\gamma^2}
+      
+      In reality the error :math:`\Delta R` is filtered with a PI (Proportional-
+      Integrator) corrector. This means that
+      
+      .. math:: \Delta \omega_{RL}^{n+1} = K_{P} \left(\frac{\Delta R}{R}\right)^{n} 
+            + K_{I} \int_0^n \! \frac{\Delta R}{R} (t) \, \mathrm{d}t. 
+      
+      Writing the same equation for :math:`\Delta \omega_{RL}^{n}` and
+      subtracting side by side we have
+      
+      .. math:: \Delta \omega_{RL}^{n+1} = \Delta \omega_{RL}^{n} + 
+            K_{P} \left[ \left(\frac{\Delta R}{R}\right)^{n} - 
+            \left(\frac{\Delta R}{R}\right)^{n-1} \right] + K_{I}^{'} 
+            \left(\frac{\Delta R}{R}\right)^{n} 
+      
+      here :math:`K_{I}^{'} = K_{I} 10 \mu s` and we approximated the integral
+      with a simple product.
+      
+      The total correction is then
+      
+      .. math:: \Delta \omega_{RF}^{n+1} = \Delta \omega_{PL}^{n+1} + \Delta \omega_{RL}^{n+1}
 

__doc/source/setup_cpp.rst

@@ -0,0 +1,7 @@
+setup_cpp module
+================
+
+.. automodule:: setup_cpp
+    :members:
+    :undoc-members:
+    :show-inheritance:

__doc/source/toolbox.rst

@@ -0,0 +1,46 @@
+toolbox package
+===============
+
+Submodules
+----------
+
+toolbox.action module
+---------------------
+
+.. automodule:: toolbox.action
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+toolbox.diffusion module
+------------------------
+
+.. automodule:: toolbox.diffusion
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+toolbox.parameter_scaling module
+--------------------------------
+
+.. automodule:: toolbox.parameter_scaling
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+toolbox.tomoscope module
+------------------------
+
+.. automodule:: toolbox.tomoscope
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: toolbox
+    :members:
+    :undoc-members:
+    :show-inheritance:

llrf/phase_loop.py

@@ -427,13 +427,7 @@ def LHC(self):
 
     def PSB(self):
         '''
-        Calculation of the PSB RF frequency correction from the phase difference
-        between beam and RF (actual synchronous phase). The transfer function is
-        
-        .. math::
-            \\Delta \\omega_{RF} = g(t) \\frac{a_0 \\Delta\\Phi_{PL}^2 + a_1 \\Delta\\Phi_{PL} + a_2 }{b_0 \\Delta\\Phi_{PL}^2 + b_1 \\Delta\\Phi_{PL} + b_2} 
-            
-        Input g through gain and [a_0, a_1, a_2, b_0, b_1, b_2] through coefficients.       
+        Phase and radial loops for PSB. See documentation on-line for details.
         '''
 
         # Average phase error while frequency is updated
@@ -450,8 +444,8 @@ def PSB(self):
             self.dphi_av = self.dphi_sum / (self.on_time[self.PL_counter] 
                              - self.on_time[self.PL_counter-1])
 
-            self.domega_PL = 0.998*self.domega_PL \
-                - self.gain[counter]*(self.dphi_av - self.dphi_av_prev)
+            self.domega_PL = 0.99803799*self.domega_PL \
+                - self.gain[counter]*(0.99901903*self.dphi_av - 0.99901003*self.dphi_av_prev)
 
             self.dphi_av_prev = self.dphi_av
             self.dphi_sum = 0.