...  ...  @@ 72,12 +72,12 @@ where the file _PartDatabase.dat_ should have two lines: 





The number in the first line is the total number of particles. In the



second line the data represents



latexmath:[$x, p_x, y,$]latexmath:[$ p_y, z, p_z$] in the local



latexmath:[x, p_x, y,]latexmath:[ p_y, z, p_z] in the local



reference frame. Their units are described in



Section [variablesopalcycl].






Please don’t try to run this mode in parallel environment. You should



believe that a single processor of the 21^st century is capable of doing



believe that a single processor of the latexmath:[21^{st}] century is capable of doing



the single particle tracking.






[[tunecalculationmode]]

...  ...  @@ 86,10 +86,10 @@ Tune Calculation mode 





In this mode, two particles are tracked, one with all data is set to



zero is the reference particle and another one is an offcentering



particle which is offcentered in both latexmath:[$r$] and



latexmath:[$z$] directions. Working in this mode, _OPALcycl_ can



calculate the betatron oscillation frequency latexmath:[$\nu_r$] and



latexmath:[$\nu_z$] for different energies to evaluate the focusing



particle which is offcentered in both latexmath:[r] and



latexmath:[z] directions. Working in this mode, _OPALcycl_ can



calculate the betatron oscillation frequency latexmath:[\nu_r] and



latexmath:[\nu_z] for different energies to evaluate the focusing



characteristics for a given magnetic field.






Like the single particle tracking mode, the initial 6D parameters of the

...  ...  @@ 126,23 +126,21 @@ will describe this in detail in Section [opalcycl:MultiBunch]. 


Variables in _OPALcycl_



~~~~~~~~~~~~~~~~~~~~~~~~






[sec:opalcycl:canon]






_OPALcycl_ uses the following canonical variables to describe the



motion of particles:






X::



Horizontal position latexmath:[$x$] of a particle in given global



Horizontal position latexmath:[x] of a particle in given global



Cartesian coordinates [m].



PX::



Horizontal canonical momentum [eV/c].



Y::



Longitudinal position latexmath:[$y$] of a particle in global



Longitudinal position latexmath:[y] of a particle in global



Cartesian coordinates [m].



PY::



Longitudinal canonical momentum [eV/c].



Z::



Vertical position latexmath:[$z$] of a particle in global Cartesian



Vertical position latexmath:[z] of a particle in global Cartesian



coordinates [m].



PZ::



Vertical canonical momentum [eV/c].

...  ...  @@ 153,20 +151,27 @@ The independent variable is: *t* [s]. 


NOTE: unit conversion of momentum in _OPALt_ and _OPALcycl_



+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++






Convert latexmath:[$\beta_x \gamma$] [dimensionless] to [mrad],



Convert latexmath:[\beta_x \gamma] [dimensionless] to [mrad],






[latexmath]



++++



(\beta\gamma)_{\text{ref}}=\frac{P}{m_0c}=\frac{Pc}{m_0c^2}



++++






latexmath:[\[\label{eq:betagamma1}



(\beta\gamma)_{\text{ref}}=\frac{P}{m_0c}=\frac{Pc}{m_0c^2},\]]



[latexmath]



++++



P_x[{mrad}]=1000\times\frac{(\beta_x\gamma)}{(\beta\gamma)_{\text{ref}}}



++++






latexmath:[\[\label{eq:betagamma2}



P_x[{mrad}]=1000\times\frac{(\beta_x\gamma)}{(\beta\gamma)_{\text{ref}}}.\]]



Convert from [eV/c] to latexmath:[\beta_x\gamma] [dimensionless],






Convert from [eV/c] to latexmath:[$\beta_x\gamma$] [dimensionless],



latexmath:[\[\label{eq:eVtobetagamma}



(\beta_x\gamma)=\sqrt{(\frac{P_x[{eV/c}]}{m_0c}+1)^21}.\]]



[latexmath]



++++



(\beta_x\gamma)=\sqrt{(\frac{P_x[{eV/c}]}{m_0c}+1)^21}.



++++






This may be deduced by analogy for the latexmath:[$y$] and



latexmath:[$z$] directions.



This may be deduced by analogy for the latexmath:[y] and



latexmath:[z] directions.






[[sec:opalcycl:localframe]]



The initial distribution in the local reference frame

...  ...  @@ 176,25 +181,31 @@ The initial distribution of the bunch, either read from file or 


generated by a distribution generator see Chapter [distribution], is



specified in the local reference frame of the _OPALcycl_ Cartesian



coordinate system see Section [opalcycl:canon]. At the beginning of the



run, the 6 phase space variables latexmath:[$(x, y, z, p_x, p_y, p_z)$]



run, the 6 phase space variables latexmath:[(x, y, z, p_x, p_y, p_z)]



are transformed to the global Cartesian coordinates using the starting



coordinates latexmath:[$r_0$] (`RINIT`), latexmath:[$\phi_0$]



(`PHIINIT`), and latexmath:[$z_0$] (`ZINIT`), and the starting momenta



latexmath:[$p_{r0}$] (`PRINIT`), and latexmath:[$p_{z0}$] (`PZINIT`) of



coordinates latexmath:[r_0] (`RINIT`), latexmath:[\phi_0]



(`PHIINIT`), and latexmath:[z_0] (`ZINIT`), and the starting momenta



latexmath:[p_{r0}] (`PRINIT`), and latexmath:[p_{z0}] (`PZINIT`) of



the reference particle, defined in the `CYCLOTRON` element



see Section [cyclotron]. Note that latexmath:[$p_{\phi 0}$] is



calculated automatically from latexmath:[$p_{total}$],



latexmath:[$p_{r0}$], and latexmath:[$p_{z0}$].



see Section [cyclotron]. Note that latexmath:[p_{\phi 0}] is



calculated automatically from latexmath:[p_{total}],



latexmath:[p_{r0}], and latexmath:[p_{z0}].






latexmath:[\[\begin{aligned}



[latexmath]



++++



\begin{aligned}



X &= x\cos(\phi_0)  y\sin(\phi_0) + r_0\cos(\phi_0) \\



Y &= x\sin(\phi_0) + y\cos(\phi_0) + r_0\sin(\phi_0) \\



Z &= z + z_0\end{aligned}\]]



Z &= z + z_0\end{aligned}



++++






latexmath:[\[\begin{aligned}



[latexmath]



++++



\begin{aligned}



PX &= (p_x+p_{r0})\cos(\phi_0)  (p_y+p_{\phi 0})\sin(\phi_0) \\



PY &= (p_x+p_{r0})\sin(\phi_0) + (p_y+p_{\phi 0})\cos(\phi_0) \\



PZ &= p_z + p_{z0}\end{aligned}\]]



PZ &= p_z + p_{z0}\end{aligned}



++++






[[sec:opalcycl:fieldmap]]



Field Maps

...  ...  @@ 208,27 +219,35 @@ cyclotron is usually measured in this frame). 


There are two possible situations. One is the real field map on median



plane of the exist cyclotron machine using measurement equipment.



Limited by the narrow gaps of magnets, in most cases with cyclotrons,



only vertical field latexmath:[$B_z$] on the median plane



(latexmath:[$z=0$]) is measured. Since the magnetic field data off the



only vertical field latexmath:[B_z] on the median plane



(latexmath:[z=0]) is measured. Since the magnetic field data off the



median plane field components is necessary for those particles with



latexmath:[$z \neq 0$], the field need to be expanded in latexmath:[$Z$]



latexmath:[z \neq 0], the field need to be expanded in latexmath:[Z]



direction. According to the approach given by Gordon and Taivassalo, by



using a magnetic potential and measured latexmath:[$B_z$] on the median



plane, at the point latexmath:[$(r,\theta, z)$] in cylindrical polar



using a magnetic potential and measured latexmath:[B_z] on the median



plane, at the point latexmath:[(r,\theta, z)] in cylindrical polar



coordinates, the third order field can be written as



latexmath:[\[\begin{aligned}



\label{eq:Bfield}






[latexmath]



++++



\begin{aligned}



B_r(r,\theta, z) & = & z\frac{\partial B_z}{\partial r}\frac{1}{6}z^3 C_r, \\



B_\theta(r,\theta, z) & = & \frac{z}{r}\frac{\partial B_z}{\partial \theta}\frac{1}{6}\frac{z^3}{r} C_{\theta}, \\



B_z(r,\theta, z) & = & B_z\frac{1}{2}z^2 C_z, \end{aligned}\]] where



latexmath:[$B_z\equiv B_z(r, \theta, 0)$] and



latexmath:[\[\begin{aligned}



\label{eq:Bcoeff}



B_z(r,\theta, z) & = & B_z\frac{1}{2}z^2 C_z, \end{aligned}



++++






where latexmath:[B_z\equiv B_z(r, \theta, 0)] and






[latexmath]



++++



\begin{aligned}



C_r & = & \frac{\partial^{3}{B_z}}{\partial r^{3}} + \frac{1}{r}\frac{\partial^{2}{B_z}}{\partial r^{2}}  \frac{1}{r^2}\frac{\partial{B_z}}{\partial r}



+ \frac{1}{r^2}\frac{\partial^{3}{B_z}}{{\partial r}{\partial \theta^2}}  2\frac{1}{r^3}\frac{\partial^{2}{B_z}}{\partial \theta^{2}}, \\



C_{\theta} & = & \frac{1}{r}\frac{\partial^{2}{B_z}}{{\partial r}{\partial \theta}} + \frac{\partial^{3}{B_z}}{{\partial r^2}{\partial \theta}}



+ \frac{1}{r^2}\frac{\partial^{3}{B_z}}{\partial \theta^{3}}, \\



C_z & = & \frac{1}{r}\frac{\partial{B_z}}{\partial r} + \frac{\partial^{2}{B_z}}{\partial r^{2}} + \frac{1}{r^2}\frac{\partial^{2}{B_z}}{\partial \theta^{2}}. \end{aligned}\]]



C_z & = & \frac{1}{r}\frac{\partial{B_z}}{\partial r} + \frac{\partial^{2}{B_z}}{\partial r^{2}} + \frac{1}{r^2}\frac{\partial^{2}{B_z}}{\partial \theta^{2}}.



\end{aligned}



++++






All the partial differential coefficients are on the median plane and



can be calculated by interpolation. _OPALcycl_ uses Lagrange’s 5point

...  ...  @@ 242,7 +261,7 @@ median plane is calculated, the field off the median plane can be 


obtained using the same expansion approach as the measured field map as



described above. However, the 3D fields of the entire working gap should



be more accurate than the expansion approach especially at the region



not so close to the median plane in latexmath:[$Z$] direction.



not so close to the median plane in latexmath:[Z] direction.






In the current version, we implemented the three specific type



fieldread functions _Cyclotron::getFieldFromFile()_ of the median plane

...  ...  @@ 253,22 +272,21 @@ fields. That which function is used is controlled by the parameters 


CARBONCYCL type



^^^^^^^^^^^^^^^






If `TYPE=CARBONCYCL`, the program requires the latexmath:[$B_z$] data



If `TYPE=CARBONCYCL`, the program requires the latexmath:[B_z] data



which is stored in a sequence shown in Figure [CYCLField].






image:./figures/cyclotron/CarbonFieldFormat.pdf[2D field map on the



median plane with primary direction corresponding to the azimuthal



direction, secondary direction to the radial direction,height=151]






We need to add 6 parameters at the header of a plain latexmath:[$B_z$]



[kG] data file, namely, latexmath:[$r_{min}$] [mm],



latexmath:[$\Delta r$] [mm], latexmath:[$\theta_{min}$] [^],



latexmath:[$\Delta \theta$] [^], latexmath:[$N_\theta$] (total data



number in each arc path of azimuthal direction) and latexmath:[$N_r$]



(total path number along radial direction). If latexmath:[$\Delta r$] or



latexmath:[$\Delta \theta$] is decimal, one can set its negative



.Figure 1: 2D field map on the median plane with primary direction corresponding to the azimuthal direction, secondary direction to the radial direction



image:./figures/cyclotron/CarbonFieldFormat.png[]






We need to add 6 parameters at the header of a plain latexmath:[B_z]



[kG] data file, namely, latexmath:[r_{min}] [mm],



latexmath:[\Delta r] [mm], latexmath:[\theta_{min}] [latexmath:[^{\circ}]],



latexmath:[\Delta \theta] [latexmath:[^{\circ}]], latexmath:[N_\theta] (total data



number in each arc path of azimuthal direction) and latexmath:[N_r]



(total path number along radial direction). If latexmath:[\Delta r] or



latexmath:[\Delta \theta] is decimal, one can set its negative



opposite number. For instance, if



latexmath:[$\Delta \theta = \frac{1}{3}{^{\circ}}$], the fourth line of



latexmath:[\Delta \theta = \frac{1}{3}{^{\circ}}], the fourth line of



the header should be set to 3.0. Example showing the above explained



format:




...  ...  @@ 332,14 +350,14 @@ finish 





By running this in ANSYS, you can get a fields file with the name



_cyc100_ANSYS.data_. You need to put 6 parameters at the header of the



file, namely, latexmath:[$r_{min}$] [mm], latexmath:[$\Delta r$] [mm],



latexmath:[$\theta_{min}$][^], latexmath:[$\Delta \theta$][^],



latexmath:[$N_\theta$](total data number in each arc path of azimuthal



direction) and latexmath:[$N_r$](total path number along radial



direction). If latexmath:[$\Delta r$] or latexmath:[$\Delta \theta$] is



file, namely, latexmath:[r_{min}] [mm], latexmath:[\Delta r] [mm],



latexmath:[\theta_{min}][^], latexmath:[\Delta \theta][^],



latexmath:[N_\theta](total data number in each arc path of azimuthal



direction) and latexmath:[N_r](total path number along radial



direction). If latexmath:[\Delta r] or latexmath:[\Delta \theta] is



decimal,one can set its negative opposite number. This is useful is the



decimal is unlimited. For instance,if



latexmath:[$\Delta \theta = \frac{1}{3} {^{\circ}}$], the fourth line of



latexmath:[\Delta \theta = \frac{1}{3} {^{\circ}}], the fourth line of



the header should be 3.0. In a word, the fields are stored in the



following format:




...  ...  @@ 376,7 +394,7 @@ following format: 


BANDRF type



^^^^^^^^^^^






If `TYPE=BANDRF`, the program requires the latexmath:[$B_z$] data format



If `TYPE=BANDRF`, the program requires the latexmath:[B_z] data format



which is same as `CARBONCYCL`. But with `BANDRF` type, the program can



also read in the 3D electric field(s). For the detail about its usage,



please see Section [cyclotron].

...  ...  @@ 388,12 +406,12 @@ Default PSI format 


If the value of `TYPE` is other string rather than above mentioned, the



program requires the data format like PSI format field file _ZYKL9Z.NAR_



and _SO3AV.NAR_, which was given by the measurement. We add 4 parameters



at the header of the file, namely, latexmath:[$r_{min}$] [mm],



latexmath:[$\Delta r$] [mm], latexmath:[$\theta_{min}$][^],



latexmath:[$\Delta \theta$][^], If latexmath:[$\Delta r$] or



latexmath:[$\Delta \theta$] is decimal,one can set its negative opposite



at the header of the file, namely, latexmath:[r_{min}] [mm],



latexmath:[\Delta r] [mm], latexmath:[\theta_{min}][latexmath:[^{\circ}]],



latexmath:[\Delta \theta][latexmath:[^{\circ}]], If latexmath:[\Delta r] or



latexmath:[\Delta \theta] is decimal,one can set its negative opposite



number. This is useful is the decimal is unlimited. For instance,if



latexmath:[$\Delta \theta = \frac{1}{3}{^{\circ}}$], the fourth line of



latexmath:[\Delta \theta = \frac{1}{3}{^{\circ}}], the fourth line of



the header should be 3.0.






....

...  ...  @@ 455,17 +473,17 @@ which is a file like 





The header parameters are ignored  user supplied parameters



`LENGTH_UNITS` and `FIELD_UNITS` are used. Fields are supplied on points



in a grid in latexmath:[$(r, y, \phi)$]. Positions and field elements



are specified by Cartesian coordinates latexmath:[$(x, y, z)$].



in a grid in latexmath:[(r, y, \phi)]. Positions and field elements



are specified by Cartesian coordinates latexmath:[(x, y, z)].






[[usersownfieldmap]]



User’s own fieldmap



^^^^^^^^^^^^^^^^^^^^






You should revise the function or write your own function according to



You should revise the function or write your own function according to



the instructions in the code to match your own field format if it is



different to above types. For more detail about the parameters of



`CYCLOTRON`, please refer to Section [cyclotron].



`CYCLOTRON`, please refer to Section <<cyclotron>>.






[[sec:opalcycl:rffieldmap]]



RF field

...  ...  @@ 476,7 +494,7 @@ Read RF voltage profile 


^^^^^^^^^^^^^^^^^^^^^^^






The RF cavities are treated as straight lines with infinitely narrow



gaps and the electric field is a latexmath:[$\delta$] function plus a



gaps and the electric field is a latexmath:[\delta] function plus a



transit time correction. the twogap cavity is treated as two



independent singlegap cavities. the spiral gap cavity is not



implemented yet. For more detail about the parameters of cyclotron

...  ...  @@ 519,22 +537,22 @@ The precision of the tracking methods is vital for the entire simulation 


process, especially for long distance tracking jobs. _OPALcycl_ uses a



fourth order RungeKutta algorithm and the second order LeapFrog



scheme. The fourth order RungeKutta algorithm needs four external



magnetic field evaluation in each time step latexmath:[$\tau$] . During



magnetic field evaluation in each time step latexmath:[\tau] . During



the field interpolation process, for an arbitrary given point the code



first interpolates Formula latexmath:[$B_z$] for its counterpart on the



first interpolates Formula latexmath:[B_z] for its counterpart on the



median plane and then expands to this give point using



Equation [Bfield].






After each time step latexmath:[$i$], the code detects whether the



After each time step latexmath:[i], the code detects whether the



particle crosses any one of the RF cavities during this step. If it



does, the time point latexmath:[$t_c$] of crossing is calculated and the



particle return back to the start point of step latexmath:[$i$]. Then



does, the time point latexmath:[t_c] of crossing is calculated and the



particle return back to the start point of step latexmath:[i]. Then



this step is divided into three substeps: first, the code tracks this



particle for latexmath:[$ t_1 = \tau  (t_ct_{i1})$]; then it



particle for latexmath:[ t_1 = \tau  (t_ct_{i1})]; then it



calculates the voltage and adds momentum kick to the particle and



refreshes its relativistic parameters latexmath:[$\beta$] and



latexmath:[$\gamma$]; and then tracks it for



latexmath:[$t_2 = \tau  t_1$].



refreshes its relativistic parameters latexmath:[\beta] and



latexmath:[\gamma]; and then tracks it for



latexmath:[t_2 = \tau  t_1].






[[spacecharge]]



Space Charge

...  ...  @@ 619,13 +637,19 @@ following format is needed. 


84.000 2278.0 0.025



....






In each line the three values represent energy latexmath:[$E$], radius



latexmath:[$r$] and latexmath:[$P_r$] for the SEO (Static Equilibrium



In each line the three values represent energy latexmath:[E], radius



latexmath:[r] and latexmath:[P_r] for the SEO (Static Equilibrium



Orbit) at starting point respectively and their units are MeV, mm and



mrad.






A bash script _tuning.sh_ is shown on the next page, to execute



_OPALcycl_ for tune calculations. To start execution, just run



_OPALcycl_ for tune calculations.






....



include::examples/tuning.sh[]



....






To start execution, just run



_tuning.sh_ which uses the input file _testcycl.in_ and the auxiliary



file _FIXPO_ SEO_. The output file is _plotdata_ from which one can plot



the tune diagram.

...  ...  @@ 655,7 +679,7 @@ revolution in `STEPPERTURN` steps; Otherwise, the particle may not go 


through a full 360^ in `STEPPERTURN` steps.






There are 3 ASCII files which store the phase space data around



latexmath:[$0$], latexmath:[$\pi/8$] and latexmath:[$\pi/4$] azimuths.



latexmath:[0], latexmath:[\pi/8] and latexmath:[\pi/4] azimuths.



Their names are the combinations of input file name (without extension)



and _Angle0.dat_, _Angle1.dat_ and _Angle2.dat_ respectively. The



data is stored in the global cylindrical coordinate system, which can be

...  ...  @@ 665,7 +689,7 @@ used to check the property of the closed orbit. 


Tune calculation mode



+++++++++++++++++++++






The tunes latexmath:[$\nu_r$] and latexmath:[$\nu_z$] of each energy are



The tunes latexmath:[\nu_r] and latexmath:[\nu_z] of each energy are



stored in a ASCII file with name _tuningresult_.






[[multiparticletrackingmode1]]

...  ...  @@ 694,7 +718,7 @@ Matched Distribution 


In order to run matched distribution simulation one has to specify a



periodic accelerator. The function call also needs the symmetry of the



machine as well as a field map. The user then specifies the emittance



latexmath:[$\pi{mmmrad}$].



latexmath:[\pi{mmmrad}].






....



/*

...  ...  @@ 720,8 +744,8 @@ The matched distribution algorithm works with normalized emittances, 


i.e. normalized by the lowest energy of the machine. The printed



emittances, however, are the geometric emittances. In addition, it has



to be paid attention that the computation is based on



latexmath:[$(x,x',y,y',z,\delta)$] instead of



latexmath:[$(x,p_{x},y,p_{y},z,p_{z})$]. Since the particles are



latexmath:[(x,x',y,y',z,\delta)] instead of



latexmath:[(x,p_{x},y,p_{y},z,p_{z})]. Since the particles are



represented in the latter coordinate system, the corresponding



transformation has to be applied to obtain the rms emittances that are



given in the output.

...  ...  @@ 730,6 +754,14 @@ given in the output. 


Input file



++++++++++






....



include::examples/matchedDistribution.in[]



....






[[output1]]



Output



++++++






....



include::examples/matchedDistribution.output[]



.... 