Zgoubi: A startup guide for the complete beginner
ZZgoubiA startup guide for the complete beginner
Annette Pressman and Kai HockOctober 17, 2018
Abstract
Zgoubi is a code which can be used to model accelerators and beamlines, comprised of magnetic and electrostatic elements. It has beenextensively developed since the mid-1980s to include circular accelera-tors and related beam physics. It has been made freely available by itsauthor on a code development site, including a Users’ Guide, a datatreatment/graphic interfacing tool, and many examples [1]. a r X i v : . [ phy s i c s . acc - ph ] M a y ontents Getting started
Zgoubi began in the early 1970s as a code to be used for ray-tracing in largespectrometers for nuclear physics. Since then Zgoubi has been adapted suchthat it can be used to design beam optics and beam lines, and to simulatenonlinear dynamics. From the mid-1980’s on, it has been developed andused extensively for the simulation of circular accelerators and storage rings,and related beam physics as spin dynamics, synchrotron radiation, short-lived beams, etc. It has been made freely available by its author on acode development site, including a Users’ Guide, a data treatment/graphicinterface program, zpop, and many examples [1–4].The code is written in FORTRAN but users have developed additionalinterfaces for data handling and visualisation. In this guide reference willbe made to MATLAB [5] scripts written for this purpose.In the Zgoubi code, particle trajectories in electromagnetic fields are cal-culated through numerical integration of the Lorentz equations. As a resultof the efficiency of the integration (through a Taylor-series based expansion)and the nature of the programming language used the computation time isvery fast. The main program array is a linear description of the Zgoubi inputfile, named zgoubi.dat. This file contains a linear definition of the latticeand beam parameters, and is written for the specific simulation required.
Zgoubi can be run on Windows or UNIX systems. However the post-processing program, zpop, requires an xterm window so is better suitedto a UNIX system. On most Windows systems it is possible to run a UNIXsystem such as Scientific Linux ( ) us-ing a product such as VirtualBox ( ), bothof which are freely available. During the installation of Scientific Linux itis possible to select the developer options which should include the requiredFORTRAN compilers needed for Zgoubi.The installation of Zgoubi on Windows and UNIX systems is covered inthe following section. It is also possible to install Zgoubi through installationof PyZgoubi (see section 1.6) [6]. It is recommended that the new user gainssome experience with Zgoubi to gain some understanding of how the codeworks before expanding to Zgoubi interfaces such as PyZgoubi.
To use Zgoubi you will need a FORTRAN compiler on your machine. ManyUNIX systems will already have a compiler installed. On a Windows ma-chine MinGW can be used [7]. 3o install MinGW;1. Visit .2. Click on ‘mingw-get-inst’, download and run the latest .exe version(figure 1a) to install to a directory of your choice, for example C: \ MinGW.Ensure to select the FORTRAN option during the install process (fig-ure 1b). Further information about this install is available on the‘Getting Started’ webpage above. (a) The MinGW download file.(b) Selecting MinGW install options.
Figure 1: Installing MinGW.4igure 2: Renaming to ’make.exe’.3. In the subfolder ’MinGW \ bin’ rename the file ’mingw32-make.exe’ to’make.exe’ (figure 2).4. Set the environmental variable with the address of the MinGW \ bindirectory (see section 1.2.2).To install Zgoubi; • Windows1. Download Zgoubi from source, e.g. http://sourceforge.net/projects/zgoubi/ and unpack to a directory of your choosing,e.g. C: \ zgoubi-5.1.0. Version 5.1.0 is stable but newer versionsare available.2. To use Zgoubi in Windows; in the main directory of the unpackedfolder and every subfolder edit the ’Makefile’ to replace everyoccurrence of ’;’ with ’&’ (figure 3b): in UNIX the semicoloncan be used separate two lines of command, but in Windows theampersand performs this function.3. Set the environmental variable with the address of the file ’zgoubi.exe’(see section 1.2.2).4. Open a command prompt (cmd.exe) in the Zgoubi folder andtype the command make . This should trigger an install of theprogram (see figure 4). In Windows the install is likely to com-plete with error messages for the install of ’zpop’. This graphicspackage needs to be run in an xterm window, which requires anX11 environment. This is not a trivial process for most Windowssystems so it will not be covered here.5 a) The zgoubi-5.1.0 contents.(b) Editing ’Makefile’. Figure 3: Editing the Zgoubi ’Makefile’ to work in Windows.Figure 4: Entering the command ’make’ on the Windows command line.6
UNIX1. If you are unsure if there is a FORTRAN compiler on your sys-tem entering the command apropos fortran will show a list ofthe commands available and their use (figure 5). If there is noinstaller available it can be obtained using the command sudoapt-get install gcc-gfortran , or through the GUI software in-staller.Figure 5: Expected response from the apropos command if FORTRANcompilers are installed.2. Download source file from http://sourceforge.net/projects/zgoubi/ (e.g. zgoubi-5.1.0.tar.bz2).3. Unpack using the command tar -xjvf zgoubi-5.1.0.tar.bz2 (figure 6).Figure 6: Unpacking Zgoubi download in Scientific Linux.4. Move the unpacked directory ’zgoubi-5.1.0’ to a directory of yourchoice, e.g. usr/local (moved to folder ~ /sw in figure 7).5. Within the directory ’zgoubi-5.1.0’ enter the command make (fig-ure 7).6. Add the location of the folder ‘zgoubi-5.1.0/zgoubi’ to the Path- see section 1.2.2. Both MinGW and Zgoubi will need adding to the ‘Path’ variable. In orderto do this, follow the instructions for the operating system used. • Windows 7igure 7: Entering the make command in Scientific Linux.1. From the Start menu right-click on ‘My Computer’ or ‘Computer’and select ‘Properties’, and ’Advanced System Settings’.2. Under the ‘Advanced’ tab select ‘Environmental Variables’ (figure8). Figure 8: Setting the Path in Windows 7.3. Here there are two boxes, the upper specifying user settings andthe lower specifying settings for all users. Be careful editing thesesettings as a mistake can affect the correct operation of the com-puter.4. In the lower box highlight ’Path’ and click ’Edit’.5. At the end of the existing entry add the address for the MinGWbin directory and the Zgoubi directory, e.g. for the base directo-ries described in the install above the add to the path ’;C: \ MinGW \ bin’and ’;C: \ zgoubi-5.1.0’ (figure 9).8igure 9: Inputing the path addresses. • UNIX1. Edit the startup file and modify the PATH variable to include thelocation of the file /zgoubi-5.1.0/zgoubi as follows (e.g. if this fileis in the directory usr/local/); – bash shell(a) edit the ‘ ~ / .bashrc’ file with the folowing;(b) PATH=”$PATH”:/usr/local/zgoubi-5.1.0/zgoubi(c) export PATH – C shell(a) edit the ‘ ~ / .cshrc’ file with the following;(b) set path=”$PATH”:/usr/local/zgoubi-5.1.0/zgoubi2. Save and close the file.3. To use the graphics program ‘zpop’ another line can be added tothe file using the location of the file ‘/zgoubi-5.1.0/zpop’ in thesame manner as above (inserted before the ‘export PATH’ linefor the bash shell) as can be seen in figure 10b below. Depending on your familiarity with Windows the following information maybe unnecessary. • You will need a text editor to edit FORTRAN files. ‘Notepad++’( http://notepad-plus-plus.org/ ) is freely available and an easy touse option for Windows. • In order to quickly open the command prompt in the correct folderon each use, paste a shortcut to the cmd.exe into the example folder,right click and under ‘Properties’, in the ‘Start in’ field copy and pastethe address of the folder containing the zgoubi.dat file.9 a) Opening the bash shell script in the home directory with text editor ’gedit’.(b) The completed shell script.
Figure 10: Editing the shell script in Scientific Linux.
In Windows the program is run from the command line (cmd.exe). In bothWindows and Linux, at the command line within the folder containing thezgoubi.dat file to be used, type zgoubi and enter (see figure 11).A successful run will output a list of elements as specified in the .dat fileand produce a results file, ‘zgoubi.res’ alongside other files such as; • zgoubi.fai - particle coordinates and spin information. This stores dataat the end of each magnet - it is useful for analysing phase space. • zgoubi.spn - spin coordinate information. • zgoubi.plt - particle coordinates and fields experienced by the particlesstepwise along the beamline. This stores data points within a magneticfield only, drift spaces don’t store tracking data in this file. • zgoubi.map - 2-D field map information.10igure 11: Running Zgoubi in Windows.The results output overview of Zgoubi is written to the zgoubi.res file.The particle tracking and field data are stored to the other output files.The data can be visualised using the Zpop code for users with access to anxterm window. Otherwise extracting the required data can be done usingother program interfaces. Dr Kai Hock has written MATLAB scripts toperform this function (see section 4.1). There are also add-on scripts suchas PyZgoubi which uses a python interface to input lattice data and analysethe results (see section 1.6).Further information about the Zgoubi output files can be found in PartD of the Zgoubi User’s Guide. The Zgoubi code comes with a graphics package called zpop. It can only berun in an xterm window which can be accessed on most UNIX systems withthe command xterm . An example of use can be seen in section 3.2.1.
The Zgoubi User’s Guide is split into four sections. The first section, Part A- ‘Description of software contents’, provides information about the physicsprocesses considered, the procedures available and the mathematical meth-ods used to perform the integrations. The section begins with a glossaryof the keywords used in the program. The keywords are how the user de-fines the accelerator lattice in the input zgoubi.dat file. Further informationabout the keywords can be found in section 4 of Part A, with details abouthow to use the keywords to be found in section B.11art B - ‘Keywords and input data formatting’ details all the keywordsused in the program. To enter lattice information into the zgoubi.dat file akeyword is used, followed by further numerical or text data to define the useof the keyword. As a simple example a drift section is defined in zgoubi.datwith the keyword ‘DRIFT’ with the length of the section (in cm). A fewother examples will be discussed in section 2 of this guide.In the introduction to Part B a description is given of how to input theinformation given for each keyword. An important thing to note is the unitsexpected for each keyword. As an example, both radians and degrees areused at different occasions. When defining a lattice careful reference to theuse of the keywords as defined in this section is strongly recommended. Theallowed values for each keyword and the units to be used can be found inpart B.In Part C - ‘Examples of input data files and output result files’ severalzgoubi.dat files are given as examples of different accelerator definitions.The resultant zgoubi.res files are also shown.The information regarding instillation and running of Zgoubi is containedwithin Part D - ‘Running Zgoubi and its post-processor/graphic interfacezpop’.
PyZgoubi is a freely available interface to Zgoubi written in python ( ). It has been designedto make reading and writing input data files easier, and takes advantage ofpython’s utilities and analysis tools to interpret the output [8]. It requires aninstallation of python with the packages of NumPy, SciPy and Matplotlib.It is also possible to install Zgoubi from the PyZgoubi installation if the OShas the GFortran compiler installed.
Python can be installed on Windows with the required packages and li-braries, NumPy, SciPy, Matplotlib either as individual modules ( see ) or through the single package options such as Anaconda( http://continuum.io/downloads ) or Enthought Canopy ( ). The 32 bit version is free to allusers. Links to these products and more are available on the PyZgoubi home-page above. The environmental variables need be amended to include the ex-ecutable ’python.exe’ and also the library site packages, which may have anaddress such as ’
C:\Users\Username\AppData\Local\Enthought\Canopy32\User\Lib\site-packages ’.After installing a python package with the above libraries PyZgoubican be downloaded from sourceforge via the homepage ( anchester.ac.uk/u/sam/pyzgoubi/ ). After downloading it can be un-packed to a directory such as ’C: \ pyzgoubi’ through a MinGW (see 1.2.1 forMinGW information) interface opened in the directory containing the tar.gzfile (for example ’filename.tar.gz’) using the following command; tar - zxvf filename . tar . gz After unpacking PyZgoubi, through a command prompt open in thepyzgoubi folder enter the command python setup.py install , or to installto a specific destination (e.g. /python/install/) with the command pythonsetup.py install -- prefix= ~ /python/install/ . The installation dialoguewill offer suggestions of amendments to be added to the environmental Pathvariable which should be updated accordingly, along with the address of thePyZgoubi executable (see section 1.2.2).Depending on the installation some small amendments may be necessaryto run PyZgoubi. A batch file in the pyzgoubi folder (titled for example’pyzgoubi.bat’) can help pyzgoubi to locate the python.exe executable. Anexample is shown below for an Enthought installation of python. @echo offpython C :\ Users \ Username \ AppData \ Local \ Enthought \ Canopy32 \ User \Scripts \ pyzgoubi %1 In the python file ’core.py’ within the ’run(... )’ loop a temporarydirectory is made with a prefix. This can cause problems in Windows whichcan be patched by changing the definition of ’tmpdir = tempfile.mdktemp(...)’ in this loop to ’tmpdir = tempfile.mkdtemp()’. On some systems the’settings.ini’ file in the .pyzgoubi folder may need to be edited to ensure thepath names are correct.
The PyZgoubi homepage contains links and information about how to in-stall the code. The required packages of SciPy, NumPy and Matplotlib canbe installed through Anaconda (link from the homepage) or other sources.Anaconda will also suggest appropriate changes to the PATH variable oroffer to adjust the shell script automatically.After a successful installation of python with these libraries on a systemwith a g77 compiler it should now be possible to download and install PyZ-goubi following the advice on the homepage and in the README includedwith the source code. The shell environment needs to be configured to in-clude the paths for the python executable and paths for the python libraries(PYTHONPATH) as advised during the installation procedure.13
Defining a lattice
To define an accelerator lattice for Zgoubi the details need to be saved into atext file named ‘zgoubi.dat’. Keeping this input file for different acceleratorsin separate directories is essential to avoid accidentally overwriting one withanother. In the file each element of the accelerator is specified in turn.
It is important to note that Zgoubi always works in local coordinates, notglobal coordinates. A right-handed system is used but the terminology maybe slightly different to other commonly used systems, most notably in thatthe x axis is along the general direction of motion. The x axis is zeroed atthe beginning of a component. In the figure below (see figure 12) the originis in the median plane on a reference curve which coincides with the opticalaxis of optical elements.Figure 12: The Zgoubi coordinate reference frame. Taken from [2]14 .2 Keywords and labels
In the zgoubi.dat file a keyword is used (in capitals and in quotes) to inputdata about every step of the lattice. The keyword and the data following itis read into the Zgoubi program. Each keyword can have two ’labels’ on thesame line. ’ KEYWORD ’ label1 label2
Although this label can be free text and used as an aide memoir, it canalso on occasion be used to produce a result. For the keyword ’MARKER’,if the second label is .plt the current coordinates will be stored to the filenamed ’zgoubi.plt’. This file can be used with Zpop to produce plots. Asanother example, if given the name of a label the keyword ’FAISTORE’will create a ’.fai’ file for storage of particle data at any element where thelabel is used. An example is given below. Here the output file will be called’zgoubi.fai’ and will store data at the exit of any element labelled label1 . ’ FAISTORE ’zgoubi . fai label1 The details about the available keywords and how to use them can befound in Part B of the Zgoubi User’s Manual. Further information andexamples of use can also be found in the Zgoubi Tutorial [9] available online.
A translation and/or rotation may be required between different elementswhich can be achieved by using the ‘CHANGREF’ keyword. The CHANGREFkeyword is used to define transverse and longitudinal shifts and a z-axis ro-tation. The entry for this keyword in Part B of the Zgoubi User’s Guide isshown in figure 13 below.Figure 13: An excerpt from the Zgoubi User’s Guide [2].The above entry gives an explanation of the function of the term, theunits required (where ‘2*cm deg’ means two separate entries in cm followedby one entry in degrees), and each entry to be in real numbers (as indicatedby ‘3*E’). As such, a rotation of the frame of reference by 10 degrees withrespect to the z axis of the original frame would be entered into zgoubi.datas below. 15
CHANGREF ’0 0 -10
The keyword for the initial particle is ’OBJET’. The input parameters arespecified over the subsequent five lines of code as can be seen in the examplecode below. With reference to Part B of the User’s Guide it can be foundthat the number on the second of these lines (with value ’2’ in the codebelow) selects options about the subsequent variables. It is again importantto note the units used (1 G = 10 − T). The units for the particle coordinatescan be in different units dependent on the number option used on line 2. ’ OBJET ’-36.689 * Rigidity - note the units of kG . cm : 10.5 eV electron2 * Selects menu option 21 1 * Total no . of particles , no . of distinct momenta-0.9 45 0.001 0.01 1 e *y , y ’, z , z ’, dl , p/ p_01 * Switch to toggle ray - tracing or not
This defined object describes the starting coordinates at the beginningof a cell in the lattice. If these coordinates were all set to zero the particlewould travel along the reference path. However this may not be the beststarting path, and may result in the particle getting lost after travellingthough a few components. Some trial and error is likely to be involved tocheck if a particle can travel through the lattice correctly. Careful selectionof a starting point for a cell - often at a point of symmetry - may meanthat the right starting coordinates can be found by varying the horizontaldisplacement (the Y value) alone.
Printing out the local particle coordinates into zgoubi.res can be done withthe keyword ’FAISCEAU’. However if the coordinates are to be stored (iesaved to file for later analysis) the keyword ’FAISTORE’ should be used.This saves the particle data to a filename (filename.fai) to be specified underthe keyword. The keyword ’MARKER’ can be used to free-text name a pointin the lattice. For example the following code would label a point in thelattice as three and produce a .fai file ’three zgoubi.fai’ which would recordthe particle data at every occurrence of the marker ’three’. ’ MARKER ’ three’ FAISTORE ’three_zgoubi . fai three2 * This value indicates how frequently the data isrecorded , i.e. every second lap around the ring Example: The EMMA lattice
EMMA (Electron Model of Many Applications) is a non-scaling FFAG accel-erator. It consists of 42 doublet quadrupole cells (see figure 14) in a 16 . −
20 MeV (kinetic en-ergy) [10]. (a) A schematic drawing of the cell.(b) A photograph of the cell.
Figure 14: The EMMA quadrupole cell [11].As the EMMA ring contains 42 replications of the same doublet cellthe lattice definition is comparatively straightforward (see figure 15) - afterdefinition the cell can be repeated 42 times to produce the complete ring.17igure 15: The completeEMMA ring [11]. Each blueand red module is the focus-ing/defocusing quadrupoledoublet, separated from thenext doublet by an RF cavity.There are no dipoles used.
Figure 16: The zgoubi.dat file for theEMMA lattice.The ’zgoubi.dat’ input file for theEMMA lattice can be seen in fig-ure 16. This section will explain thecontent of this file line by line us-ing some of the components as de-scribed in the previous section.Along the right hand side of thedata in this file it can be seen thateach keyword has been labelled innumerical order. This is not an es-sential part of the file, but can makematching the keyword to the out-put in the zgoubi.res file more sim-ple. It can be seen in figure 17that the results file zgoubi.res num-bers each lattice element (the num-ber before the keyword). Labellingeach element in the input file withthe corresponding number can makeit easier to locate an input elementwith its output. For this lattice,with only 16 keywords used, it isnot very difficult to identify eachelement in the zgoubi.res file andmatch it to the corresponding ele-ment in the zgoubi.dat file but inmore complicated lattices this is lessstraightforward.Line 1 of the zgoubi.dat file isfor free text, in order to identify thelattice. The first keywords neededfor this, and most lattices, are ’OBJET’ and ’PARTICUL’. OBJET definesthe object, i.e. the initial particle coordinates and PARTICUL defines the18igure 17: Except from zgoubi.res regarding keyword ’OBJET’.characteristics of the particles in the beam. For EMMA the beam consists ofelectrons. The zgoubi.res file output gives further details about the particlefrom the input data from OBJET and PARTICUL (see figure 18). It isstrongly advised to check this file after defining a lattice to ensure thisoutput is correct, and the data has been input correctly.Figure 18: Except from zgoubi.res regarding keyword ’PARTICUL’.At this point in the input file the cell can be defined. In EMMA the cellconsists of the quadrupole doublet followed by a drift of 21 cm. The nextcell is then at an angle to the first. As there are 42 cells in the complete ringthis angle is 360 ◦ /
42 = 8 . ◦ (actually − . ◦ with respect to the x axisto describe a rotation towards the centre of the ring) . For this lattice thedrift section has been described as two 10 . . − . ◦ . The other half of the drift cavityis defined at the end of the cell on line 42. This defines a cell representedby the schematic picture in figure 19.Figure 19: Schematic drawing of the cell as defined in zgoubi.dat.The CHANGREF on line 12 of zgoubi.dat rotates the coordinate systemfrom ’a’ in figure 19 to one with the x-axis parallel to ’b’. The followingCHANGREF on line 14 then performs a translation to move the coordinatesto ’b’, with the x-axis in line with the centre of the defocusing quadrupole.Line 16 then defines the defocusing quadrupole, with the label ’defoc’ andis followed by a CHANGREF which reverses the previous translation andmoves the coordinates to ’c’. After a further drift section there is anotherchange of coordinates to ’d’ before the definition of the focusing quadrupoleon line 31. One final CHANGREF moves the coordinates to ’e’ before thefinal drift section is defined at line 42.The defocusing and focusing quadrupoles are defined at lines 16 and 31respectively. The initial value of ’2’ is an instruction to print the field andcoordinates along the trajectories. The following lines (18 and 33) define thelength, radius and magnetic field at the pole tip for each quadrupole. Thefocusing magnet can be seen to have a negative value for this field. Bothquadrupoles are then defined with four lines consisting of zero values. Theselines can be used to define the fringe magnetic fields - the ’entrance’ and ’exit’fringe fields. With zero values a ’sharp edge’ magnetic field approximationis used.On lines 23 and 38 three values are entered to define the ’XPAS’ - thisdefines the number of steps for the integration process in the entrance field,main field and exit field of each component. If passed a single value a step20ength in cm would be used.At line 44 a marker is placed. This itself has no impact on the beam (ifgiven a second keyword of .plt data from this point in the lattice will bestored in the zgoubi.plt file) but marks the position on the lattice with thelabel bpm str . The following keyword ’FAISTORE’ stores particle infor-mation in a .fai file given as an argument, here zgoubi.fai . The informationis stored at every occurence of the labels given on line 46 which in this caseis bpm str. So the net result of lines 44-47 is to produce a file output ofparticle data at the end of the cell where the marker is placed.The ’REBLOTTE’ keyword on line 48 of figure 16 is a command to re-peat the zgoubi.dat file. Here it is given the values ’42 0 99’ which translatesas 42 repetitions (i.e. one complete ring) with the ’0’ specifying a level ofverbosity in the .res file and the ’99’ indicating that the particle coordinatesat the end of one pass are used as initial coordinates for the next pass. Totrack the particle through several laps of the ring a multiple of 42 would beused for the first value. A run can be performed by typing the command zgoubi in the directory con-taining EMMA’s zgoubi.dat file (within a command prompt in Windows);this can be seen in figure 20, the run produces four output files.
If used in UNIX the output can be visualised with Zpop which is part of theZgoubi package. In the following example the same zgoubi.dat file is usedas input as seen in figure 16.In order to produce data plots first Zgoubi should be run as in theprevious section to produce .fai and/or .plt files, as can be seen in figure21a. An xterm window can then be opened with the command ’xterm’. Inthe xterm window the command zpop (see figure 21b) then opens the menu21c and a blank tektronix window. Firstly option 1, ’Run Zgoubi’ shouldbe selected in the xterm window to produce a zpop.log file. After this hasbeen done the other options can be selected to examine different data. Alist of the available variables to plot can be seen in figure 22. There is alsoan analysis package as part of Zpop accessible through option 8 of the mainmenu. This offers options as can be seen in figure 23 below.As an example of the possible options, it is possible to plot the trackof the particle through the lattice quadrupole by loading the zgoubi.plt file(see figure 24). Plotting the lab X and Y coordinates then produces a plotshowing one cell in the lab coordinates. The quadrupoles can be seen astrapezoidal rather than rectangular shapes as the axis have different scales.The reference track which passes through the centre of the quadrupoles can21igure 20: A run of Zgoubi in a Windows command prompt showing thedirectory contents before and after the run.be seen changing direction in line with the ’CHANGREF’ commands fromzgoubi.dat. The particle tracking data can be seen as two arcs of datathrough the quadrupoles. The trapezoids representing the quadrupoles donot define the physical extent of the magnetic field, so it can be seen thatalthough the particle track happens outside of the defocusing quadrupoletrapezoid the track is still curved by its magnetic field.The zgoubi.fai file is useful for analysing the phase space. From theZpop main menu choosing the menu options to open the file ’zgoubi.fai’allows plotting of a choice of variables. If the variables Z and Z’ are chosen(see figure 21d) and then plotted the following phase space chart can beproduced (see figure 25b). As the running of Zpop requires an xterm window it it not ideally suitedto a Windows system. In this situation a MATLAB script can be used toextract the data from the zgoubi.fai or zgoubi.plt file (see Appendix 4.1).The output from these files can be seen in figure 26.22 a) A run of zgoubi.dat .(b) Entering the command zpop in theinitial xterm window. (c) The initial Zpop menu in the xtermwindow.(d) The menu ready to plot Z vs Z’ in the xterm window. Figure 21: Output from Zgoubi on a Scientific Linux OS.23igure 22: The variables available to plot within Zpop for the zgoubi.fai file.Figure 23: The analysis menu in zpop.24 a) The menu showing the selected options for the plot below using the zgoubi.pltfile.(b) A plot to show the particle track (in lab coordinates) through the magneticfields of the quadrupoles of one cell. The .plt file only contains tracking datathough magnetic fields.
Figure 24: An example of using zgoubi.plt in zpop.25 a) The xterm output from plotting Z vs Z’ .(b) The graphical output of Z vs Z’ in the tektronix window with a ’matchedellipse’. Figure 25: Output from Zpop on a Scientific Linux OS.26igure 26: Output from MATLAB scripts analysing zgoubi.fai (see Ap-pendix 4.1) in Windows. 27 .2.3 EMMA with PyZgoubi
The identical lattice can be defined using the PyZgoubi script found in ap-pendix 4.2. A version of this script and other EMMA examples are includedin the PyZgoubi downloaded package. As with Zgoubi, the program is runfrom a command line (cmd.exe in Windows) open in the directory contain-ing the particular script. The ’emma ellipse.py’ script is run by entering thecommand pyzgoubi emma ellipse.py (see figure 27a). The output of thescript begins with a print to screen of the zgoubi.res file produced (figure27b), followed by other instructions from the code - in this case a list of theZ,P values and a graphical output (see figure 27c).An advantage of PyZgoubi is the ability to use python analysis toolson the resultant data. Included in the PyZgoubi downloaded package aresample EMMA scripts to calculate the closed orbits, tune, Twiss profilesand magnetic apertures for the lattice. Futher information about the useof PyZgoubi can be found at . 28 a) Entering the command to run.(b) The initial output of the run.(c) The graphical output of the script.
Figure 27: Running emma ellipse.py in Windows.29
Appendix
The following codes were written by Dr. Kai Hock to extract and plot datafrom the Zgoubi output files using MATLAB.
This code extracts data from zgoubi.plt. function [Y , T , Z , P , X , S , BX , BY , BZ ] = get_zgoubi_data (filename ) % filename = ’ zgoubi . plt ’;% s1 = ’e ’; % particle label fid = fopen ( filename , ’r ’);fgets ( fid );fgets ( fid );fgets ( fid );fgets ( fid );s = fscanf ( fid , ’\% s ’, 1) ;fgets ( fid );a = fscanf ( fid , ’\% f ’, 3) ;fgets ( fid );c = fscanf ( fid , ’\% f ’, 3) ;fgets ( fid );b = fscanf ( fid , ’\% f ’, 8) ;n = 1;while feof ( fid ) == 0,Y(n) = a (2) ;T(n) = a (3) ;Z(n) = c (1) ;P(n) = c (2) ;S(n) = c (3) ;X(n) = b (5) ;BX (n) = b (6) ;BY (n) = b (7) ;BZ (n) = b (8) ;n = n + 1;fgets ( fid );fgets ( fid );s = fscanf ( fid , ’\% s ’, 1) ;fgets ( fid );a = fscanf ( fid , ’\% f ’, 3) ;fgets ( fid ); = fscanf ( fid , ’\% f ’, 3) ;fgets ( fid );b = fscanf ( fid , ’\% f ’, 8) ;endfclose ( fid ); In this script the previous code is called to extract the data which is thenplotted. clearfilename = ’ zgoubi . plt ’;[Y , T , Z , P , X , S , BX , BY , BZ ] = get_zgoubi_data ( filename );close allfiguresubplot (221) , plot (S /100 , BZ /10 , ’. ’)set ( gca , ’ fontsize ’ ,12)xlabel ( ’S(cid:32)(m) ’, ’ fontsize ’, 14)ylabel ( ’BZ (cid:32)(T) ’, ’ fontsize ’, 14)subplot (222) , plot (S /100 , Y /100 , ’. ’)set ( gca , ’ fontsize ’ ,12) % xlabel (’S (m) ’, ’ fontsize ’, 14) ylabel ( ’Y(cid:32)(m) ’, ’ fontsize ’, 14)subplot (223) , plot (S /100 , T /1000 , ’. ’)set ( gca , ’ fontsize ’ ,12) % xlabel (’S (m) ’, ’ fontsize ’, 14) ylabel ( ’T(cid:32)( rad ) ’, ’ fontsize ’, 14)figuresubplot (221) , plot (S /100 , BY /10 , ’. ’)set ( gca , ’ fontsize ’ ,12) % xlabel (’S (m) ’, ’ fontsize ’, 14) ylabel ( ’BY (cid:32)(T) ’, ’ fontsize ’, 14)subplot (222) , plot (S /100 , Z /100 , ’. ’)set ( gca , ’ fontsize ’ ,12)xlabel ( ’S(cid:32)(m) ’, ’ fontsize ’, 14)ylabel ( ’Z(cid:32)(m) ’, ’ fontsize ’, 14)subplot (223) , plot (S /100 , P /1000 , ’. ’)set ( gca , ’ fontsize ’ ,12)xlabel ( ’S(cid:32)(m) ’, ’ fontsize ’, 14)ylabel ( ’P(cid:32)( rad ) ’, ’ fontsize ’, 14) igureplot (Z /100 , P /1000 , ’o ’)set ( gca , ’ fontsize ’, 20)xlabel ( ’Z(cid:32)(m) ’, ’ fontsize ’, 24)ylable ( ’Z ’’(cid:32)( rad ) ’, ’ fontsize ’, 24) This script, emma ellipse.py, will write the zgoubi.dat file for the EMMAlattice, print the ’zgoubi.res’ output to screen and plot a chart of Z vs Z’ (orZ vs P). print " running emma example "import pylab as pltemma = Line ( ’ emma ’)xpas = (20 ,20 ,20)cells = 42angle = -360/ cellsd_offset = 34.048 * mmf_offset = 7.514 * mm mma . add ( CHANGREF ( YCE = f_offset * cm_ ))emma . add ( QUADRUPO ( ’ foc ’, XL = fq * cm_ , R_0 = fr * cm_ , B_0 = fb * kgauss_ ,XPAS = xpas , IL =2) )emma . add ( CHANGREF ( YCE =- f_offset * cm_ ))emma . add ( DRIFT ( ’ld ’, XL = ld * cm_ /2) )emma . add ( FAISCNL ( FNAME = ’ zgoubi . fai ’))emma . add ( REBELOTE (K =99 , NPASS =42) )emma . add ( END () )rigidity = ke_to_rigidity (10.5 e6 , 0.51099892 e6 )ob . set ( BORO =- rigidity )ob . add (Y = -0.9 , T =45 , Z =0.001 , P =0.01 , D =1)print emma . output ()res = emma . run () eferences [1] ”Zgoubi”, F. M´eot, http://sourceforge.net/projects/zgoubi/ [2] ”Zgoubi User’s Guide”, F. M´eot, 2012, [3] ”Zgoubi”, C. Lapoire, R. Basset, F. Zimmermann and F.Ruggiero, https://oraweb.cern.ch/pls/hhh/code_website.disp_code?code_name=Zgoubi [4] [5] Mathworks, 2013, [6] ”PyZgoubi - a python interface to Zgoubi”, S.Tygier, [7] MinGW, 2013, [8] ”PyZgoubi Documentation”, S. Tygier, [9] ”Zgoubi Tutorial - A course for (potential) users”, F. M´eot, 2009, ftp://ftp3.ie.freebsd.org/pub/sourceforge/z/zg/zgoubi/exemples/tutorial/lecture.pdf [10] ”EMMA, The World’s First Non-Scaling FFAG Accelerator”, S.L.Smith, 2009, http://accelconf.web.cern.ch/AccelConf/PAC2009/papers/we4pbi01.pdf [11] ”Fixed Field Alternating Gradient Accelerators (FFAG)”, S.Machida,2012, http://cas.web.cern.ch/cas/Granada-2012/Lectures/GranadaLectures/Machida.pdfhttp://cas.web.cern.ch/cas/Granada-2012/Lectures/GranadaLectures/Machida.pdf