Merge pull request #539 from piotrskowronski/master

 Bug fixes and documentation for RF cavities

Makefile_test

@@ -75,7 +75,7 @@ test-ptc-twiss-old1 test-ptc-twiss-old2 test-ptc-twiss-old3 test-ptc-twiss-old4
 test-ptc-twiss-5D test-ptc-twiss-5Dt test-ptc-twiss-56D test-ptc-twiss-56Dt test-ptc-twiss-56Dl test-ptc-twiss-56Dtl test-ptc-twiss-6D test-ptc-twiss-6D-ALS \
 test-ptc-twiss-accel-56D test-ptc-twiss-56Dt-ini_map_man test-ptc-twiss-56Dt-ini_mtx_man test-ptc-twiss-56Dt-ini_mtx_tbl \
 test-ptc-normal test-ptc-twiss-normal-genfu test-ptc-twiss-normal-5D test-ptc-twiss-normal-6D test-ptc-twiss-maptable \
-test-ptc-track test-ptc-track-2 test-ptc-track-3 test-ptc-track-4 \
+test-ptc-track test-ptc-track-2 test-ptc-track-3 test-ptc-track-4 test-ptc-track-5 \
 test-ptc-track-acd test-ptc-track-acd-2 \
 test-ptc-trackline test-ptc-trackline-2 test-ptc-trackline-3 \
 test-rfmultipole-ptc-1 \

doc/latexuguide/elements.tex

@@ -899,7 +899,11 @@ \section{RF Cavity}
     of non-zero dispersion may not close as expected. Therefore, it is best
     to perform \texttt{TWISS} in 4D only, \textsl{i.e.} with cavities
     switched off. If 6D is needed one has to use the
-    \hyperref[sec:ptc-twiss]{\texttt{PTC\_TWISS}} command.  
+    \hyperref[sec:ptc-twiss]{\texttt{PTC\_TWISS}} command. 
+    Please refer to \hyperref[sec:ptc-setswitch]{\texttt{PTC\_SETSWITCH}} command,
+    in particular to \texttt{TIME} and \texttt{TOTALPATH} switches,
+    concerning RF behaviour of cavities in PTC.
+
 \end{itemize}
 
 The \texttt{RFCAVITY} can also have attributes that only become active in 

doc/latexuguide/ptc-general.tex

@@ -134,32 +134,8 @@ \section{PTC\_CREATE\_LAYOUT}
 
   \ttitem{TIME} a logical flag to control which coordinate system 
   is being used. \\ (Default=~true) \\ \\
-  This option changes the canonical coordinate system depending
-  whether the calculation is done in 5D or 6D: 
-  \begin{madlist}
-    \ttitem{5D} if \texttt{TIME} is true, the fifth coordinate is
-    \hyperref[subsec:tables-canon]{\texttt{PT}},
-    $p_t = \Delta E / p_0 c$ \\  
-    if \texttt{TIME} is false, the fifth coordinate is
-    \hyperref[subsec:tables-canon]{\texttt{DELTAP}},
-    $\delta_p = \Delta p / p_0$
-
-    \ttitem{6D} if \texttt{TIME} is true, the
-    \hyperref[subsec:tables-canon]{\madx coordinate system}
-    \{$-ct$, $p_t$\} is used. \\    
-    if \texttt{TIME} is false, the second \ptc coordinate system
-    \{-pathlength, $\delta_p$\} is used. 
-  \end{madlist}
-
- \textbf{Note:} at small energy ($\beta_0 << 1$),
- momentum-dependent variables like dispersion will depend  strongly on
- the choice of  the logical input variable "time".  In fact, the
- derivative ($\frac{\partial}{\partial \delta_p}$)  and
- ($\frac{\partial}{\partial p_t}$)  are different by the
- factor $\beta_0$. One would  therefore typically  choose
- the option "time=false",  which sets the fifth variable to
- the relative momentum deviation $\delta_p$.
-
+  Please see \texttt{TIME} of \hyperref[sec:ptc-setswitch]{\texttt{PTC\_SETSWITCH}}
+  command for more details.
 
   \ttitem{MODEL} an integer to switch between models:\\
   1 for "Drift-Kick-Drift";  (Default value)\\ 
@@ -267,10 +243,24 @@ \section{PTC\_SETSWITCH}
 	Switch ensures exact misalignment treatment.   
 
 	\ttitem{TOTALPATH} (Default: false)\\
-	If true, the 6th variable of PTC, i.e. 5th of MAD-X, is the total
-	path.  \\
+	If true, the 6th variable of PTC, i.e. 5th of MAD-X, is the total path.  \\
 	If false it is deviation from the reference particle,
-	which is normally the closed orbit for closed layouts.    
+	which is normally the closed orbit for closed layouts. \\
+	This switch changes behaviour of the RF cavities, 
+	including RF multipoles and crab cavities. 
+	If it is false, the time of flight effect between the cavities
+	(or the ring length) is ignored because the kick is proportional to \\
+	$sin(2\pi \cdot \rm{FREQ} \cdot t/c + \rm{LAG})$, where $t$ is the time coodinate.
+	So only distance from the synchronous particle plays a role.
+	For example, changing ring length will not affect the cavity.
+	On the other hand, it gurantees that the defined LAG is observed.
+	Conversely, if \texttt{TOTALPATH} is true then $t$ becomes the total time of flight
+	so its effect is accounted for. In the case when cavity is detuned 
+	the closed orbit momentum will change and in ray tracking phase slippage from turn
+	to turn will be seen. However, \texttt{LAG} of cavities needs to be 
+	carefuly calculated because its phasing will depend on its position. 
+	Naturally, in cases with only one RF cavity the closed orbit search will automatically
+	determine the offset. 
 
 	\ttitem{RADIATION} (Default: false)\\    
 	Sets the radiation switch/internal state of PTC. In PTC basically all the elements
@@ -285,9 +275,9 @@ \section{PTC\_SETSWITCH}
 	\ttitem{STOCHASTIC} (Default: false)\\    
 	Sets the stochastic switch/internal state of PTC. 
 	It enables stochastic emission of photons in ray tracking,  
-                    it only affects \ttitem{PTC\_TRACK} and \ttitem{PTC\_TRACKLINE}.
+                    it only affects \texttt{PTC\_TRACK} and \texttt{PTC\_TRACKLINE}.
 	The emission is calculated during map tracking therefore 
-	\ttitem{PTC\_TWISS} or \ttitem{PTC\_NORMAL} needs to be invoked before 
+	\texttt{PTC\_TWISS} or \texttt{PTC\_NORMAL} needs to be invoked before 
 	launching the tracking. Every tracked ray will receive the same stochastic kicks.
 
 	\ttitem{MODULATION} (Default: false)\\    
@@ -306,7 +296,33 @@ \section{PTC\_SETSWITCH}
 
 	\ttitem{TIME} (Default: true)\\  
 	If true, Selects time of flight (\textit{cT} to be precise) rather
-	than path length as the 6th variable of PTC, i.e. 5th of MAD-X.     
+	than path length as the 6th variable of PTC, i.e. 5th of MAD-X. \\
+                    This option changes the canonical coordinate system depending
+	whether the calculation is done in 5D or 6D: 
+	 \begin{madlist}
+	   \ttitem{5D} if \texttt{TIME} is true, the fifth coordinate is
+	   \hyperref[subsec:tables-canon]{\texttt{PT}},
+	   $p_t = \Delta E / p_0 c$ \\  
+	   if \texttt{TIME} is false, the fifth coordinate is
+	   \hyperref[subsec:tables-canon]{\texttt{DELTAP}},
+	   $\delta_p = \Delta p / p_0$
+
+	   \ttitem{6D} if \texttt{TIME} is true, the
+	   \hyperref[subsec:tables-canon]{\madx coordinate system}
+	   \{$-ct$, $p_t$\} is used. \\    
+	   if \texttt{TIME} is false, the second \ptc coordinate system
+	   \{-pathlength, $\delta_p$\} is used. 
+	 \end{madlist}
+
+	\textbf{Note:} at small energy ($\beta_0 << 1$),
+	momentum-dependent variables like dispersion will depend  strongly on
+	the choice of  the logical input variable \ttitem{TIME}.  In fact, the
+	derivative ($\frac{\partial}{\partial \delta_p}$)  and
+	($\frac{\partial}{\partial p_t}$)  are different by the
+	factor $\beta_0$. One would  therefore typically  choose
+	the option \ttitem{TIME=false},  which sets the fifth variable to
+	the relative momentum deviation $\delta_p$.
+
 
 \end{madlist}
 

libs/ptc/src/Sra_fitting.f90

@@ -3439,13 +3439,14 @@ SUBROUTINE FIND_ORBIT_LAYOUT_noda_object(FIX0,STATE,eps,TURNS,fibre1,node1) ! Fi
     TYPE (fibre), POINTER :: C
     TYPE (integration_node), POINTER :: t
     logical(lp) APERTURE,use_bmad_units_temp
-    logical isStableFixPoint
+    logical isStableFixPoint, didPhaseJump
     INTEGER TURNS0,trackflag
 
 
     fix=fix0
 
-
+    didPhaseJump = .false.
+
     tot=0
     if(present(fibre1)) then
      ring=>fibre1%parent_layout
@@ -3734,15 +3735,26 @@ SUBROUTINE FIND_ORBIT_LAYOUT_noda_object(FIX0,STATE,eps,TURNS,fibre1,node1) ! Fi
 
     if (ND2 == 6.and.check_longitudinal) then
       isStableFixPoint = is_ORBIT_STABLE(FIX,EPS,STAT,fibre1,node1)
-      if (isStableFixPoint .eqv. .false.) then
+
+      if (isStableFixPoint .eqv. .false. ) then
+        if (didPhaseJump ) then
+
+          messagelost= "Found unstable fixed point"
+          xlost=fix
+          check_stable=my_false
+
+        else
 
          if(global_verbose) print*,"Orbit seemed to be unstable in longitudinal"
-
-         fix = fix0
-         fix(6)= fix(6)+ clight/freqmin/2
 
-         goto 1111
+           fix = fix0
+           fix(6)= fix(6)+ clight/freqmin/2
+
+           didPhaseJump = .true.  ! it is protection against 
 
+           goto 1111
+         endif
+
        endif
     endif
 

src/madx_ptc_module.f90

@@ -1057,7 +1057,7 @@ subroutine ptc_input()
        key%list%volt=bvk*node_value('volt ')
        freq=c_1d6*node_value('freq ')
 
-       key%list%lag=node_value('lag ')*twopi 
+       key%list%lag = -node_value('lag ')*twopi
 
        ! correction for time of flight through cavity
        ! we want particle with t=0 to be not accelerated
@@ -1210,7 +1210,7 @@ subroutine ptc_input()
        key%magnet="twcavity"
        key%list%volt=bvk*node_value('volt ')
        freq=c_1d6*node_value('freq ')
-       key%list%lag=node_value('lag ')*twopi
+       key%list%lag=-node_value('lag ')*twopi
        offset_deltap=get_value('ptc_create_layout ','offset_deltap ')
        default=default+totalpath0 !fringe field calculation vitally relies on it!!!!
        if(offset_deltap.ne.zero) then
@@ -1245,7 +1245,7 @@ subroutine ptc_input()
        !       key%list%ks(1)= (+/-)  node_value('volt ')*c_1d_3
        !
        freq=c_1d6*node_value('freq ')
-       key%list%lag=node_value('lag ')*twopi+pih
+       key%list%lag=-node_value('lag ')*twopi+pih
        offset_deltap=get_value('ptc_create_layout ','offset_deltap ')
        if(offset_deltap.ne.zero) then
           default = getintstate()
@@ -1284,7 +1284,7 @@ subroutine ptc_input()
         ! parameters to modulate the nominal parameters. No modulation in MADX implemented.
         key%list%DC_ac = zero
         key%list%A_ac = zero
-        key%list%theta_ac = node_value('lag ') ! it is ignored with fast modulationtype = 1
+        key%list%theta_ac = -node_value('lag ') ! it is ignored with fast modulationtype = 1
 
 
         key%list%clockno_ac = getclockidx()
@@ -1317,7 +1317,7 @@ subroutine ptc_input()
         ! parameters to modulate the nominal parameters. No modulation in MADX implemented.
         key%list%DC_ac = zero
         key%list%A_ac = zero
-        key%list%theta_ac = node_value('lag ')
+        key%list%theta_ac = -node_value('lag ')
 
         key%list%clockno_ac = getclockidx()
 
@@ -1331,7 +1331,7 @@ subroutine ptc_input()
        key%magnet="rfcavity"
        key%list%volt=bvk*node_value('volt ')
        freq=c_1d6*node_value('freq ')
-       key%list%lag=node_value('lag ')*twopi
+       key%list%lag=-node_value('lag ')*twopi
 
        print*,"RF frequency " , freq," Hz, lag ", key%list%lag, " [radian]"
 

src/madx_ptc_twiss.f90

@@ -3459,7 +3459,7 @@ subroutine putMinMaxRmses(summary_table_name,startorbit)
       call double_to_table_curr( summary_table_name,'orbit_y ',  startorbit(3))
       call double_to_table_curr( summary_table_name,'orbit_py ', startorbit(4))
       call double_to_table_curr( summary_table_name,'orbit_pt ', startorbit(5))
-      call double_to_table_curr( summary_table_name,'orbit_-cT ',startorbit(6))
+      call double_to_table_curr( summary_table_name,'orbit_-cT ',-startorbit(6))
 
       xrms = sqrt(sum2Orbit / nobsOrbit)
 

tests/share/ALS/als.seqx

@@ -52,7 +52,7 @@ BEND1 : RBEND,L= LBEND, ANGLE=ALPHA, k1=-0.778741;
 
 CAVM:MARKER;
 rfvolt = 0.2d0;
-CAV:RFCAVITY,L=0.2000,VOLT:=rfvolt,FREQ=500.;
+CAV:RFCAVITY,L=0.2000,VOLT:=rfvolt,FREQ=500., LAG=0.25;
 
  sfline: line = (1*sf);
  sdline: line = (1*sd);

tests/test-ptc-track-5/FFAG.ptc.twiss.cfg

@@ -0,0 +1,2 @@
+85-88   *   skip        # date, version
+*       *   any abs=1e-14 rel=1e-14