This notebook was created by Sergey Tomin for Workshop: Designing future X-ray FELs. Source and license info is on GitHub. August 2016.

Tutorial N2. Tracking.

As an example, we will use lattice file (converted to Ocelot format) of the European XFEL Injector.

This example will cover the following topics:

• calculation of the linear optics for the European XFEL Injector.
• Tracking of the particles in first and second order approximation without collective effects.

Coordiantes

Coordinates in Ocelot are following: $$ \left (x, \quad x' = \frac{p_x}{p_0} \right), \qquad \left (y, \quad y' = \frac{p_y}{p_0} \right), \qquad \left (\Delta s = c\tau, \quad p = \frac{\Delta E}{p_0 c} \right)$$

Requirements

• injector_lattice.py - input file, the Injector lattice.
• beam_130MeV.ast - input file, initial beam distribution in ASTRA format.

If you want to see injector_lattice.py file you can run following command (lattice file is very large):

$ %load injector_lattice.py

The variable cell contains all the elements of the lattice in right order.

And again Ocelot will work with class MagneticLattice instead of simple sequence of element. So we have to run following command.

1. Design optics calculation of the European XFEL Injector

Remark

For convenience reasons, we define optical functions starting at the gun by backtracking of the optical functions derived from ASTRA (or similar space charge code) at 130 MeV at the entrance to the first quadrupole. The optical functions we thus obtain have obviously nothing to do with the actual beam envelope form the gun to the 130 MeV point.

Because we work with linear accelerator we have to define initial energy and initial twiss paramters in order to get correct twiss functions along the Injector.

2. Tracking in first and second order approximation without any collective effects

Remark

Because of the reasons mentioned above, we start the beam tracking from the first quadrupole after RF cavities.

Loading of beam distribution

In order to perform tracking we have to have beam distribution. We will load beam distribution from a ASTRA file ('beam_distrib.ast'). And we convert the Astra beam distribution to Ocelot format - ParticleArray. ParticleArray is designed for tracking. In order to work with converters we have to import specific module from ocelot.adaptors

from ocelot.adaptors.astra2ocelot import *

After importing ocelot.adaptors.astra2ocelot we can use converter astraBeam2particleArray() to load and convert. As you will see beam distribution consists of 200 000 particles (that is why loading can take a few second), charge 250 pC, initial energy is about 6.5 MeV.

ParticleArray is a class which includes several parameters and methods.

• ParticleArray.rparticles is a 2D numpy array (6 x N) with coordinates of particles in $$ParticleArray.rparticles = [\vec{x_0}, \vec{x_1}, ..., \vec{x_n}], $$ where $$\vec{x_n} = (x_n, x_n', y_n, y_n', \tau_n, p_n)^T$$
• ParticleArray.s is the longitudinal coordinate of the reference particle in [m].
• ParticleArray.E is the energy of the reference particle in [GeV].
• ParticleArray.q_array - is a 1D numpy array of the charges each (macro) particles in [C]

Selection of the tracking order and lattice for the tracking.

MagneticLattice(sequence, start=None, stop=None, method=MethodTM()) have wollowing arguments:

• sequence - list of the elements,
• start - first element of the lattice. If None, then lattice starts from the first element of the sequence,
• stop - last element of the lattice. If None, then lattice stops by the last element of the sequence,
• method=MethodTM() - method of the tracking. MethodTM() class assigns transfer map to every element. By default all elements are assigned first order transfer map - TransferMap. One can create one's own map, but there are following predefined maps:
  • TransferMap - first order matrices.
  • SecondTM - 2nd order matrices.
  • KickTM - kick applyed.
  • RungeKuttaTM - Runge-Kutta integrator is applyed, but required 3D magnetic field function element.mag_field = lambda x, y, z: (Bx, By, Bz) (see example ocelot/demos/ebeam/tune_shift.py)

Tracking

for tracking we have to define following objects:

• Navigator defines step (dz) of tracking and which, if it exists, physical process will be applied at each step. In order to add collective effects (Space charge, CSR or wake) method add_physics_proc() must be run.

  • Method:
    • Navigator.add_physics_proc(physics_proc, elem1, elem2)
      • physics_proc - physics process, can be CSR, SpaceCharge or Wake,
      • elem1 and elem2 - first and last elements between which the physics process will be applied.

• track(MagneticLatice, ParticleArray, Navigator) - the function performs tracking through the lattice [lat] of the particles [p_array]. This function also calculate twiss parameters of the beam distribution on each tracking step.

Current profile

Beam distribution