Zgoubi
A startup guide for the complete beginner

Zgoubi began in the early 1970’s as a code to be used for ray-tracing in large spectrometers for nuclear physics. Since then Zgoubi has been adapted such that it can be used to design beam optics and beam lines, and to simulate nonlinear dynamics. From the mid-1980’s on, it has been developed and used 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 a code development site, including a Users’ Guide, a data treatment/graphic interface program, zpop, and many examples [1, 2, 3, 4].

The code is written in FORTRAN but users have developed additional interfaces for data handling and visualisation. In this guide reference will be made to MATLAB [5] scripts written for this purpose.

In the Zgoubi code, particle trajectories in electromagnetic fields are calculated through numerical integration of the Lorentz equations. As a result of the efficiency of the integration (through a Taylor-series based expansion) and the nature of the programming language used the computation time is very fast. The main program array is a linear description of the Zgoubi input file, named zgoubi.dat. This file contains a linear definition of the lattice and 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 suited to a UNIX system. On most Windows systems it is possible to run a UNIX system such as Scientific Linux (https://www.scientificlinux.org/) using a product such as VirtualBox (https://www.virtualbox.org/), both of which are freely available. During the installation of Scientific Linux it is possible to select the developer options which should include the required FORTRAN compilers needed for Zgoubi.

The installation of Zgoubi on Windows and UNIX systems is covered in the following section. It is also possible to install Zgoubi through installation of PyZgoubi (see section 1.6)[6]. It is recommended that the new user gains some experience with Zgoubi to gain some understanding of how the code works before expanding to Zgoubi interfaces such as PyZgoubi.

In Windows the program is run from the command line (cmd.exe). In both Windows and Linux, at the command line within the folder containing the zgoubi.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 file and produce a results file, ‘zgoubi.res’ alongside other files such as;

• •

  zgoubi.fai - particle coordinates and spin information. This stores data at 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 particles stepwise along the beamline. This stores data points within a magnetic field only, drift spaces don’t store tracking data in this file.

• •

  zgoubi.map - 2-D field map information.

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 an xterm window. Otherwise extracting the required data can be done using other program interfaces. Dr Kai Hock has written MATLAB scripts to perform this function (see section 4.1). There are also add-on scripts such as PyZgoubi which uses a python interface to input lattice data and analyse the results (see section 1.6).

Further information about the Zgoubi output files can be found in Part D of the Zgoubi User’s Guide.

The Zgoubi code comes with a graphics package called zpop. It can only be run in an xterm window which can be accessed on most UNIX systems with the 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 physics processes considered, the procedures available and the mathematical methods used to perform the integrations. The section begins with a glossary of the keywords used in the program. The keywords are how the user defines the accelerator lattice in the input zgoubi.dat file. Further information about the keywords can be found in section 4 of Part A, with details about how to use the keywords to be found in section B.

Part B - ‘Keywords and input data formatting’ details all the keywords used in the program. To enter lattice information into the zgoubi.dat file a keyword is used, followed by further numerical or text data to define the use of the keyword. As a simple example a drift section is defined in zgoubi.dat with the keyword ‘DRIFT’ with the length of the section (in cm). A few other examples will be discussed in section 2 of this guide.

In the introduction to Part B a description is given of how to input the information given for each keyword. An important thing to note is the units expected for each keyword. As an example, both radians and degrees are used at different occasions. When defining a lattice careful reference to the use of the keywords as defined in this section is strongly recommended. The allowed values for each keyword and the units to be used can be found in part B.

In Part C - ‘Examples of input data files and output result files’ several zgoubi.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 contained within Part D - ‘Running Zgoubi and its post-processor/graphic interface zpop’.

PyZgoubi is a freely available interface to Zgoubi written in python (http://www.hep.manchester.ac.uk/u/sam/pyzgoubi/). It has been designed to make reading and writing input data files easier, and takes advantage of python’s utilities and analysis tools to interpret the output[8]. It requires an installation of python with the packages of NumPy, SciPy and Matplotlib. It is also possible to install Zgoubi from the PyZgoubi installation if the OS has the GFortran compiler installed.

It is important to note that Zgoubi always works in local coordinates, not global coordinates. A right-handed system is used but the terminology may be slightly different to other commonly used systems, most notably in that the x axis is along the general direction of motion. The x axis is zeroed at the beginning of a component. In the figure below (see figure 12) the origin is in the median plane on a reference curve which coincides with the optical axis of optical elements.

In the zgoubi.dat file a keyword is used (in capitals and in quotes) to input data about every step of the lattice. The keyword and the data following it is read into the Zgoubi program. Each keyword can have two ’labels’ on the same line.

Although this label can be free text and used as an aide memoir, it can also 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 file named ’zgoubi.plt’. This file can be used with Zpop to produce plots. As another 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 the label 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.

The details about the available keywords and how to use them can be found in Part B of the Zgoubi User’s Manual. Further information and examples of use can also be found in the Zgoubi Tutorial[9] available online.

A translation and/or rotation may be required between different elements which can be achieved by using the ‘CHANGREF’ keyword. The CHANGREF keyword is used to define transverse and longitudinal shifts and a z-axis rotation. The entry for this keyword in Part B of the Zgoubi User’s Guide is shown in figure 13 below.

The above entry gives an explanation of the function of the term, the units required (where ‘2*cm deg’ means two separate entries in cm followed by one entry in degrees), and each entry to be in real numbers (as indicated by ‘3*E’). As such, a rotation of the frame of reference by 10 degrees with respect to the z axis of the original frame would be entered into zgoubi.dat as below.

The keyword for the initial particle is ’OBJET’. The input parameters are specified over the subsequent five lines of code as can be seen in the example code below. With reference to Part B of the User’s Guide it can be found that the number on the second of these lines (with value ’2’ in the code below) selects options about the subsequent variables. It is again important to note the units used ($1$ G = $10^{-4}$ T). The units for the particle coordinates can be in different units dependent on the number option used on line 2.

This defined object describes the starting coordinates at the beginning of a cell in the lattice. If these coordinates were all set to zero the particle would travel along the reference path. However this may not be the best starting path, and may result in the particle getting lost after travelling though a few components. Some trial and error is likely to be involved to check if a particle can travel through the lattice correctly. Careful selection of a starting point for a cell - often at a point of symmetry - may mean that the right starting coordinates can be found by varying the horizontal displacement (the Y value) alone.

Printing out the local particle coordinates into zgoubi.res can be done with the keyword ’FAISCEAU’. However if the coordinates are to be stored (ie saved to file for later analysis) the keyword ’FAISTORE’ should be used. This saves the particle data to a filename (filename.fai) to be specified under the keyword. The keyword ’MARKER’ can be used to free-text name a point in the lattice. For example the following code would label a point in the lattice as three and produce a .fai file ’three_zgoubi.fai’ which would record the particle data at every occurrence of the marker ’three’.

The ’zgoubi.dat’ input file for the EMMA lattice can be seen in figure 16. This section will explain the content of this file line by line using some of the components as described in the previous section.

Along the right hand side of the data in this file it can be seen that each keyword has been labelled in numerical order. This is not an essential part of the file, but can make matching the keyword to the output in the zgoubi.res file more simple. It can be seen in figure 17 that the results file zgoubi.res numbers each lattice element (the number before the keyword). Labelling each element in the input file with the corresponding number can make it easier to locate an input element with its output. For this lattice, with only 16 keywords used, it is not very difficult to identify each element in the zgoubi.res file and match it to the corresponding element in the zgoubi.dat file but in more complicated lattices this is less straightforward.

Line 1 of the zgoubi.dat file is for free text, in order to identify the lattice. The first keywords needed for this, and most lattices, are ’OBJET’ and ’PARTICUL’. OBJET defines the object, i.e. the initial particle coordinates and PARTICUL defines the characteristics of the particles in the beam. For EMMA the beam consists of electrons. The zgoubi.res file output gives further details about the particle from the input data from OBJET and PARTICUL (see figure 18). It is strongly advised to check this file after defining a lattice to ensure this output is correct, and the data has been input correctly.

At this point in the input file the cell can be defined. In EMMA the cell consists of the quadrupole doublet followed by a drift of $21$ cm. The next cell is then at an angle to the first. As there are 42 cells in the complete ring this angle is $360^{\circ}/42=8.57^{\circ}$ (actually $-8.57^{\circ}$ with respect to the x axis to describe a rotation towards the centre of the ring) . For this lattice the drift section has been described as two $10.5$ cm sections at the beginning and end of the cell. This means the rotation of reference frame appears within the cell description rather than at the end as expected. The reason for this relates to the initial injection of particles in the OBJET definition. In order to obtain a stable orbit around the ring some trial and error with the initial particle coordinates is required. Using the middle of the drift space as the start of the cell allows a stable orbit to be found by varying the horizontal displacement (Y) alone. If the start/end of the cell involved the rotation the angle theta (T) would need to be varied too, making the process of finding a stable orbit more complicated. So it can be seen in figure 16 at line 10 the first drift section of $10.5$ cm is defined, which is then followed by a change in reference frame of a rotation of $-8.57^{\circ}$. The other half of the drift cavity is defined at the end of the cell on line 42. This defines a cell represented by the schematic picture in figure 19.

The CHANGREF on line 12 of zgoubi.dat rotates the coordinate system from ’a’ in figure 19 to one with the x-axis parallel to ’b’. The following CHANGREF on line 14 then performs a translation to move the coordinates to ’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’ and is followed by a CHANGREF which reverses the previous translation and moves the coordinates to ’c’. After a further drift section there is another change of coordinates to ’d’ before the definition of the focusing quadrupole on line 31. One final CHANGREF moves the coordinates to ’e’ before the final drift section is defined at line 42.

The defocusing and focusing quadrupoles are defined at lines 16 and 31 respectively. The initial value of ’2’ is an instruction to print the field and coordinates along the trajectories. The following lines (18 and 33) define the length, radius and magnetic field at the pole tip for each quadrupole. The focusing magnet can be seen to have a negative value for this field. Both quadrupoles are then defined with four lines consisting of zero values. These lines can be used to define the fringe magnetic fields - the ’entrance’ and ’exit’ fringe fields. With zero values a ’sharp edge’ magnetic field approximation is used.

On lines 23 and 38 three values are entered to define the ’XPAS’ - this defines 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 step length in cm would be used.

At line 44 a marker is placed. This itself has no impact on the beam (if given a second keyword of .plt data from this point in the lattice will be stored in the zgoubi.plt file) but marks the position on the lattice with the label bpm_str. The following keyword ’FAISTORE’ stores particle information in a .fai file given as an argument, here zgoubi.fai. The information is stored at every occurence of the labels given on line 46 which in this case is bpm_str. So the net result of lines 44-47 is to produce a file output of particle 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 repeat the zgoubi.dat file. Here it is given the values ’42 0 99’ which translates as 42 repetitions (i.e. one complete ring) with the ’0’ specifying a level of verbosity in the .res file and the ’99’ indicating that the particle coordinates at the end of one pass are used as initial coordinates for the next pass. To track the particle through several laps of the ring a multiple of 42 would be used for the first value.

A run can be performed by typing the command zgoubi in the directory containing EMMA’s zgoubi.dat file (within a command prompt in Windows); this can be seen in figure 20, the run produces four output files.

The following codes were written by Dr. Kai Hock to extract and plot data from the Zgoubi output files using MATLAB.

This script, emma_ellipse.py, will write the zgoubi.dat file for the EMMA lattice, print the ’zgoubi.res’ output to screen and plot a chart of Z vs Z’ (or Z vs P).