

:toc:



[[chp:opalcycl]]






:stem: latexmath



:sectnums:






[[chp:opalcycl]]



_OPALcycl_










[[introduction]]



Introduction



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






_OPALcycl_, as one of the flavors of the _OPAL_ framework, is a fully



threedimensional parallel beam dynamics simulation program dedicated to



future high intensity cyclotrons and FFAG. it tracks multiple particles



which takes into account the space charge effects. For the first time in



the cyclotron community, _OPALcycl_ has the capability of tracking



multiple bunches simultaneously and take into account the beambeam



effects of the radially neighboring bunches (we call it neighboring



bunch effects for short) by using a selfconsistent numerical simulation



model.






Apart from the multiparticle simulation mode, _OPALcycl_ also has two



other serial tracking modes for conventional cyclotron machine design.



One mode is the single particle tracking mode, which is a useful tool



for the preliminary design of a new cyclotron. It allows one to compute



basic parameters, such as reference orbit, phase shift history, stable



region, and matching phase ellipse. The other one is the tune



calculation mode, which can be used to compute the betatron oscillation



frequency. This is useful for evaluating the focusing characteristics of



a given magnetic field map.






In addition, the widely used plugin elements, including collimator,



radial profile probe, septum, trimcoil field and charge stripper, are



currently implemented in _OPALcycl_. These functionalities are very



useful for designing, commissioning and upgrading of cyclotrons and



FFAGs.






[[trackingmodes]]



Tracking modes



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






According to the number of particles defined by the argument `npart` in



`beam` see Chapter [beam] , _OPALcycl_ works in one of the following



three operation modes automatically.






[[singleparticletrackingmode]]



Single Particle Tracking mode



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






In this mode, only one particle is tracked, either with acceleration or



not. Working in this mode, _OPALcycl_ can be used as a tool during the



preliminary design phase of a cyclotron.






The 6D parameters of a single particle in the initial local frame must



be read from a file. To do this, in the _OPAL_ input file, the command



line `DISTRIBUTION` see Chapter [distribution] should be defined like



this:






....



Dist1: DISTRIBUTION, TYPE=fromfile, FNAME="PartDatabase.dat";



....






where the file _PartDatabase.dat_ should have two lines:






....



1



0.001 0.001 0.001 0.001 0.001 0.001



....






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



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



the single particle tracking.






[[tunecalculationmode]]



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



characteristics for a given magnetic field.






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



two particles in the local reference frame must be read from a file,



too. In the file should has three lines:






....



2



0.0 0.0 0.0 0.0 0.0 0.0



0.001 0.0 0.0 0.0 0.001 0.0



....






When the total particle number equals 2, this mode is triggered



automatically. Only the element `CYCLOTRON` in the beam line is used and



other elements are omitted if any exists.






Please don’t try to run this mode in parallel environment, either.






[[multiparticletrackingmode]]



Multiparticle tracking mode



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






In this mode, large scale particles can be tracked simultaneously,



either with space charge or not, either single bunch or multibunch,



either serial or parallel environment, either reading the initial



distribution from a file or generating a typical distribution, either



running from the beginning or restarting from the last step of a former



simulation.






Because this is the main mode as well as the key part of _OPALcycl_, we



will describe this in detail in Section [opalcycl:MultiBunch].






[[sec:variablesopalcycl]]



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



Cartesian coordinates [m].



PX::



Horizontal canonical momentum [eV/c].



Y::



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



coordinates [m].



PZ::



Vertical canonical momentum [eV/c].






The independent variable is: *t* [s].






[[noteunitconversionofmomentuminopaltandopalcycl]]



NOTE: unit conversion of momentum in _OPALt_ and _OPALcycl_



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






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






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



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






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],



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



(\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.






[[sec:opalcycl:localframe]]



The initial distribution in the local reference frame



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






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)$]



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



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}$].






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}\]]






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}\]]






[[sec:opalcycl:fieldmap]]



Field Maps



~~~~~~~~~~






In _OPALcycl_, the magnetic field on the median plane is read from an



ASCII type file. The field data should be stored in the cylinder



coordinates frame (because the field map on the median plane of the



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



median plane field components is necessary for those particles with



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



coordinates, the third order field can be written as



latexmath:[\[\begin{aligned}



\label{eq:Bfield}



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}



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}\]]






All the partial differential coefficients are on the median plane and



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



formula.






The other situation is to calculate the field on the median plane or the



3D fields of the working gap for interesting region numerically by



creating 3D model using commercial software, such as TOSCA, ANSOFT and



ANSYS during the design phase of a new machine. If the field on the



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.






In the current version, we implemented the three specific type



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



fields. That which function is used is controlled by the parameters



`TYPE` of `CYCLOTRON` see Section [cyclotron] in the input file.






[[carboncycltype]]



CARBONCYCL type



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






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



opposite number. For instance, if



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:






....



3.0e+03



10.0



0.0



3.0



300



161



1.414e03 3.743e03 8.517e03 1.221e02 2.296e02



3.884e02 5.999e02 8.580e02 1.150e01 1.461e01



1.779e01 2.090e01 2.392e01 2.682e01 2.964e01



3.245e01 3.534e01 3.843e01 4.184e01 4.573e01



......



....






[[cyciaetype]]



CYCIAE type



^^^^^^^^^^^






If `TYPE=CYCIAE`, the program requires data format given by ANSYS10.0.



This function is originally for the 100MeV cyclotron of CIAE, whose



isochronous fields is numerically computed by by ANSYS. The median plane



fields data is output by reading the APDL (ANSYS Parametric Design



Language) script during the postprocessing phase (you may need to do



minor changes to adapt your own cyclotron model):






....



/post1



resume,solu,db



csys,1



nsel,s,loc,x,0



nsel,r,loc,y,0



nsel,r,loc,z,0



PRNSOL,B,COMP






CSYS,1



rsys,1






*do,count,0,200



path,cyc100_Ansys,2,5,45



ppath,1,,0.01*count,0,,1



ppath,2,,0.01*count/sqrt(2),0.01*count/sqrt(2),,1






pdef,bz,b,z



paget,data,table






*if,count,eq,0,then



/output,cyc100_ANSYS,dat



*STATUS,data,,,5,5



/output



*else



/output,cyc100_ANSYS,dat,,append



*STATUS,data,,,5,5



/output



*endif



*enddo



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



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



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



following format:






....



0.0



10.0



0.0e+00



1.0e+00



90



201



PARAMETER STATUS DATA ( 336 PARAMETERS DEFINED)



(INCLUDING 17 INTERNAL PARAMETERS)






LOCATION VALUE



1 5 1 0.537657876



2 5 1 0.538079473



3 5 1 0.539086731



......



44 5 1 0.760777286



45 5 1 0.760918663



46 5 1 0.760969074






PARAMETER STATUS DATA ( 336 PARAMETERS DEFINED)



(INCLUDING 17 INTERNAL PARAMETERS)






LOCATION VALUE



1 5 1 0.704927299



2 5 1 0.705050993



3 5 1 0.705341275



......



....






[[bandrftype]]



BANDRF type



^^^^^^^^^^^






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].






[[defaultpsiformat]]



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



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



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



the header should be 3.0.






....



1900.0



20.0



0.0



3.0



LABEL=S03AV



CFELD=FIELD NREC= 141 NPAR= 3



LPAR= 7 IENT= 1 IPAR= 1



3 141 135 30 8



8 70



LPAR= 1089 IENT= 2 IPAR= 2



0.100000000E+01 0.190000000E+04 0.200000000E+02 0.000000000E+00 0.333333343E+00



0.506500015E+02 0.600000000E+01 0.938255981E+03 0.100000000E+01 0.240956593E+01



0.282477260E+01 0.340503168E+01 0.419502926E+01 0.505867147E+01 0.550443363E+01



0.570645094E+01 0.579413509E+01 0.583940887E+01 0.586580372E+01 0.588523722E+01



......



....






[[dfieldmap]]



3D fieldmap



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






It is additionally possible to load 3D fieldmaps for tracking through



_OPALcycl_. 3D fieldmaps are loaded by sequentially adding new field



elements to a line, as is done in _OPALt_. It is not possible to add RF



cavities while operating in this mode. In order to define ring



parameters such as initial ring radius a `RINGDEFINITION` type is loaded



into the line, followed by one or more `SBEND3D` elements.






....



ringdef: RINGDEFINITION, HARMONIC_NUMBER=6, LAT_RINIT=2350.0, LAT_PHIINIT=0.0,



LAT_THETAINIT=0.0, BEAM_PHIINIT=0.0, BEAM_PRINIT=0.0,



BEAM_RINIT=2266.0, SYMMETRY=4.0, RFFREQ=0.2;






triplet: SBEND3D, FMAPFN="fdftoscafieldmap.table", LENGTH_UNITS=10., FIELD_UNITS=1e4;






l1: Line = (ringdef, triplet, triplet);



....






The fieldmap with file name _fdftoscafieldmap.table_ is loaded,



which is a file like






....



422280 422280 422280 1



1 X [LENGU]



2 Y [LENGU]



3 Z [LENGU]



4 BX [FLUXU]



5 BY [FLUXU]



6 BZ [FLUXU]



0



194.01470 0.0000000 80.363520 0.68275932346E07 5.3752492577 0.28280706805E07



194.36351 0.0000000 79.516210 0.42525693524E07 5.3827955117 0.17681348191E07



194.70861 0.0000000 78.667380 0.19766168358E07 5.4350026348 0.82540823165E08



<continues>



....






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)$].






[[usersownfieldmap]]



User’s own fieldmap



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






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].






[[sec:opalcycl:rffieldmap]]



RF field



~~~~~~~~






[[readrfvoltageprofile]]



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



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



cavities, see Section [cavitycycl].






The voltage profile of a cavity gap is read from ASCII file. Here is an



example:






....



6



0.00 0.15 2.40



0.20 0.65 2.41



0.40 0.98 0.66



0.60 0.88 1.59



0.80 0.43 2.65



1.00 0.05 1.71



....






The number in the first line means 6 sample points and in the following



lines the three values represent the normalized distance to the inner



edge of the cavity, the normalized voltage and its derivative



respectively.






[[read3drffieldmap]]



Read 3D RF fieldmap



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






The 3D RF fieldmap can be read from H5hut type file. This is useful for



modeling the central region electric fields which usually has complicate



shapes. For the detail about its usage, please see Section [cyclotron].






Please note that in this case, the E field is treated as a part of



`CYCLOTRON` element, rather than a independent `RFCAVITY` element.






[[particletrackingandacceleration]]



Particle Tracking and Acceleration



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






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



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



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



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



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



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$].






[[spacecharge]]



Space Charge



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






_OPALcycl_ uses the same solvers as _OPALt_ to calculate the space



charge effects see Chapter [fieldsolver].






Typically, the space charge field is calculated once per time step. This



is no surprise for the second order BorisBuneman time integrator



(leapfroglike scheme) which has per default only one force evaluation



per step. The fourth order RungeKutta integrator keeps the space charge



field constant for one step, although there are four external field



evaluations. There is an experimental multipletimestepping (MTS)



variant of the BorisBuneman/leapfrogmethod, which evaluates space



charge only every N^th step, thus greatly reducing computation time



while usually being still accurate enough.






[[sec:opalcycl:MultiBunch]]



Multibunch Mode



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






The neighboring bunches problem is motivated by the fact that for high



intensity cyclotrons with small turn separation, single bunch space



charge effects are not the only contribution. Along with the increment



of beam current, the mutual interaction of neighboring bunches in radial



direction becomes more and more important, especially at large radius



where the distances between neighboring bunches get increasingly small



and even they can overlap each other. One good example is PSI 590MeV



Ring cyclotron with a current of about 2mA in CW operation and the beam



power amounts to 1.2MW. An upgrade project for Ring is in process with



the goal of 1.8MW CW on target by replacing four old aluminum resonators



by four new copper cavities with peak voltage increasing from about



0.7MW to above 0.9MW. After upgrade, the total turn number is reduced



from 200 turns to less than 170 turns. Turn separation is increased a



little bit, but still are at the same order of magnitude as the radial



size of the bunches. Hence once the beam current increases from 2mA to



3mA, the mutual space charge effects between radially neighboring



bunches can have significant impact on beam dynamics. In consequence, it



is important to cover neighboring bunch effects in the simulation to



quantitatively study its impact on the beam dynamics.






In _OPALcycl_, we developed a new fully consistent algorithm of



multibunch simulation. We implemented two working modes, namely ,



`AUTO` and `FORCE`. In the first mode, only a single bunch is tracked



and accelerated at the beginning, until the radial neighboring bunch



effects become an important factor to the bunches’ behavior. Then the



new bunches will be injected automatically to take these effects into



account. In this way, we can save time and memory, and more important,



we can get higher precision for the simulation in the region where



neighboring bunch effects are important. In the other mode, multibunch



simulation starts from the injection points.






In the space charge calculation for multibunch, the computation region



covers all bunches. Because the energy of the bunches is quite



different, it is inappropriate to use only one particle rest frame and a



single Lorentz transformation any more. So the particles are grouped



into different energy bins and in each bin the energy spread is



relatively small. We apply Lorentz transforming, calculate the space



charge fields and apply the back Lorentz transforming for each bin



separately. Then add the field data together. Each particle has a ID



number to identify which energy bin it belongs to.






[[input]]



Input



~~~~~






All the three working modes of _OPALcycl_ use an input file written in



`mad` language which will be described in detail in the following



chapters.






For the *Tune Calculation mode*, one additional auxiliary file with the



following format is needed.






....



72.000 2131.4 0.240



74.000 2155.1 0.296



76.000 2179.7 0.319



78.000 2204.7 0.309



80.000 2229.6 0.264



82.000 2254.0 0.166



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



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



_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.






[[output]]



Output



~~~~~~






[[singleparticletrackingmode1]]



Single Particle Tracking mode



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






The intermediate phase space data is stored in an ASCII file which can



be used to the plot the orbit. The file’s name is combined by input file



name (without extension) and _trackOrbit.dat_. The data are stored in



the global Cartesian coordinates. The frequency of the data output can



be set using the option `SPTDUMPFREQ` of `OPTION` statement



see Section [option]






The phase space data per `STEPSPERTURN` (a parameter in the `TRACK`



command) steps is stored in an ASCII file. The file’s name is a



combination of input file name (without extension) and



_afterEachTurn.dat_. The data is stored in the global cylindrical



coordinate system. Please note that if the field map is ideally



isochronous, the reference particle of a given energy take exactly one



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.



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



used to check the property of the closed orbit.






[[tunecalculationmode1]]



Tune calculation mode



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






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



stored in a ASCII file with name _tuningresult_.






[[multiparticletrackingmode1]]



Multiparticle tracking mode



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






The intermediate phase space data of all particles and some interesting



parameters, including RMS envelop size, RMS emittance, external field,



time, energy, length of path, number of bunches and tracking step, are



stored in the H5hut fileformat [bib:howison2010] and can be analyzed



using the H5root [bib:schietinger]. The frequency of the data output can



be set using the `PSDUMPFREQ` option of `OPTION` statement



see Section [option]. The file is named like the input file but the



extension is _.h5_.






The intermediate phase space data of central particle (with ID of 0) and



an offcentering particle (with ID of 1) are stored in an ASCII file.



The file’s name is combined by the input file name (without extension)



and _trackOrbit.dat_. The frequency of the data output can be set using



the `SPTDUMPFREQ` option of `OPTION` statement see Section [option].






[[matcheddistribution]]



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}$].






....



/*



* specify periodic accelerator



*/



l1 = ...






/*



* try finding a matched distribution



*/



Dist1:DISTRIBUTION, TYPE=GAUSSMATCHED, LINE=l1, FMAPFN=...,



MAGSYM=..., EX = ..., EY = ..., ET = ...;



....






[[example]]



Example



^^^^^^^






Simulation of the PSI Ring Cyclotron at 580MeV and current 2.2mA. The



program finds a matched distribution followed by a bunch initialization



according to the matched covariance matrix. +



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



represented in the latter coordinate system, the corresponding



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



given in the output.






[[inputfile]]



Input file



++++++++++






[[output1]]



Output



++++++ 