Notebook

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

An Introduction to Ocelot¶

Ocelot is a multiphysics simulation toolkit designed for studying FEL and storage ring based light sources. Ocelot is written in Python. Its central concept is the writing of python's scripts for simulations with the usage of Ocelot's modules and functions and the standard Python libraries.

Ocelot includes following main modules:

Charged particle beam dynamics module (CPBD)
- optics
- tracking
- matching
- collective effects (description can be found here )
  - Space Charge (true 3D Laplace solver)
  - CSR (Coherent Synchrotron Radiation) (1D model with arbitrary number of dipoles) (under development).
  - Wakefields (Taylor expansion up to second order for arbitrary geometry).
- MOGA (Multi Objective Genetics Algorithm). (under development but we have already applied it for a storage ring application)
Native module for spontaneous radiation calculation
FEL calculations: interface to GENESIS and pre/post-processing
Modules for online beam control and online optimization of accelerator performances. Work1, work2, work3, work4.

Ocelot extensively uses Python's NumPy (Numerical Python) and SciPy (Scientific Python) libraries, which enable efficient in-core numerical and scientific computation within Python and give you access to various mathematical and optimization techniques and algorithms. To produce high quality figures Python's matplotlib library is used.

It is an open source project and it is being developed by physicists from The European XFEL, DESY (Germany), NRC Kurchatov Institute (Russia).

We still have no documentation but you can find a lot of examples in ocelot/demos/

Ocelot user profile¶

Ocelot is designed for researchers who want to have the flexibility that is given by high-level languages such as Matlab, Python (with Numpy and SciPy) or Mathematica. However if someone needs a GUI it can be developed using Python's libraries like a PyQtGraph or PyQt.

For example, you can see GUI for SASE optimization (uncomment and run next block)

In [1]:

from IPython.display import Image
#Image(filename='gui_example.png')

Tutorials¶

Preliminaries: Setup & introduction
Beam dynamics
Tutorial N1. Linear optics.. Web version.
- Linear optics. Double Bend Achromat (DBA). Simple example of usage OCELOT functions to get periodic solution for a storage ring cell.
Tutorial N2. Tracking.. Web version.
- Linear optics of the European XFEL Injector.
- Tracking. First and second order.
Tutorial N3. Space Charge.. Web version.
- Tracking through RF cavities with SC effects and RF focusing.
Tutorial N4. Wakefields.. Web version.
- Tracking through corrugated structure (energy chirper) with Wakefields
Tutorial N5. CSR.. Web version.
- Tracking trough bunch compressor with CSR effect.
Tutorial N6. RF Coupler Kick.. Web version.
- Coupler Kick. Example of RF coupler kick influence on trajjectory and optics.
Tutorial N7. Lattice design.. Web version.
- Lattice design, twiss matching, twiss backtracking

Preliminaries¶

The tutorial includes 7 simple examples dediacted to beam dynamics and optics. However, you should have a basic understanding of Computer Programming terminologies. A basic understanding of Python language is a plus.

This tutorial requires the following packages:¶

Python 3.4-3.6 (python 2.7 can work as well)
numpy version 1.8 or later: http://www.numpy.org/
scipy version 0.15 or later: http://www.scipy.org/
matplotlib version 1.5 or later: http://matplotlib.org/
ipython version 2.4 or later, with notebook support: http://ipython.org

Optional to speed up python

numexpr (version 2.6.1)
pyfftw (version 0.10)

The easiest way to get these is to download and install the (very large) Anaconda software distribution.

Alternatively, you can download and install miniconda. The following command will install all required packages:

$ conda install numpy scipy matplotlib ipython-notebook

Ocelot installation¶

you have to download from GitHub zip file.
Unzip ocelot-master.zip to your working folder /your_working_dir/.
Rename folder ../your_working_dir/ocelot-master to /your_working_dir/ocelot.
Add ../your_working_dir/ to PYTHONPATH
- Windows 7: go to Control Panel -> System and Security -> System -> Advance System Settings -> Environment Variables.
and in User variables add /your_working_dir/ to PYTHONPATH. If variable PYTHONPATH does not exist, create it

Variable name: PYTHONPATH

Variable value: ../your_working_dir/
- Linux:
```
$ export PYTHONPATH=/your_working_dir/:$PYTHONPATH
```

To launch "ipython notebook" or "jupyter notebook"¶

in command line run following commands:

$ ipython notebook

$ ipython notebook --notebook-dir="path_to_your_directory"

$ jupyter notebook --notebook-dir="path_to_your_directory"

Checking your installation¶

You can run the following code to check the versions of the packages on your system:

(in IPython notebook, press shift and return together to execute the contents of a cell)

In [2]:

import IPython
print('IPython:', IPython.__version__)

import numpy
print('numpy:', numpy.__version__)

import scipy
print('scipy:', scipy.__version__)

import matplotlib
print('matplotlib:', matplotlib.__version__)

import ocelot
print('ocelot:', ocelot.__version__)

IPython: 5.1.0
numpy: 1.11.2
scipy: 0.18.1
matplotlib: 1.5.1
initializing ocelot...
ocelot: 17.05.rc

Tutorial N1. Double Bend Achromat.¶

We designed a simple lattice to demonstrate the basic concepts and syntax of the optics functions calculation. Also, we chose DBA to demonstrate the periodic solution for the optical functions calculation.

In [1]:

from __future__ import print_function

# the output of plotting commands is displayed inline within frontends, 
# directly below the code cell that produced it
%matplotlib inline

# import from Ocelot main modules and functions
from ocelot import *

# import from Ocelot graphical modules
from ocelot.gui.accelerator import *

initializing ocelot...

Creating lattice¶

Ocelot has following elements: Drift, Quadrupole, Sextupole, Octupole, Bend, SBend, RBend, Edge, Multipole, Hcor, Vcor, Solenoid, Cavity, Monitor, Marker, Undulator.

In [2]:

# defining of the drifts
D1 = Drift(l=2.)
D2 = Drift(l=0.6)
D3 = Drift(l=0.3)
D4 = Drift(l=0.7)
D5 = Drift(l=0.9)
D6 = Drift(l=0.2)

# defining of the quads
Q1 = Quadrupole(l=0.4, k1=-1.3)
Q2 = Quadrupole(l=0.8, k1=1.4)
Q3 = Quadrupole(l=0.4, k1=-1.7)
Q4 = Quadrupole(l=0.5, k1=1.3)

# defining of the bending magnet
B = Bend(l=2.7, k1=-.06, angle=2*pi/16., e1=pi/16., e2=pi/16.)

# defining of the sextupoles
SF = Sextupole(l=0.01, k2=1.5) #random value
SD = Sextupole(l=0.01, k2=-1.5) #random value

# cell creating
cell = (D1, Q1, D2, Q2, D3, Q3, D4, B, D5, SD, D5, SF, D6, Q4, D6, SF, D5, SD, D5, B, D4, Q3, D3, Q2, D2, Q1, D1)

hint: to see a simple description of the function put cursor inside () and press Shift-Tab* or you can type sign ? before function. To extend dialog window press + *

The cell is a list of the simple objects which contain a physical information of lattice elements such as length, strength, voltage and so on. In order to create a transport map for every element and bind it with lattice object we have to create new Ocelot object - MagneticLattice() which makes these things automatically.

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

sequence - list of the elements,

other paramenters we will consider in tutorial N2.

In [3]:

lat = MagneticLattice(cell)

# to see total lenth of the lattice 
print("length of the cell: ", lat.totalLen, "m")

length of the cell:  20.34 m

Optical function calculation¶

Uses:

twiss() function and,
Twiss() object contains twiss parameters and other information at one certain position (s) of lattice

To calculate twiss parameters you have to run twiss(lattice, tws0=None, nPoints=None) function. If you want to get a periodic solution leave tws0 by default.

You can change the number of points over the cell, If nPoints=None, then twiss parameters are calculated at the end of each element. twiss() function returns list of Twiss() objects.

You will see the Twiss object contains more information than just twiss parameters.¶

In [4]:

tws=twiss(lat)

# to see twiss paraments at the begining of the cell, uncomment next line
# print(tws[0])

# to see twiss paraments at the end of the cell, uncomment next line
print(tws[0])

emit_x  = 0.0
emit_y  = 0.0
beta_x  = 0.527161369596
beta_y  = 0.51659778953
alpha_x = 1.21756687446e-15
alpha_y = -1.83246512915e-15
gamma_x = 1.89695235211
gamma_y = 1.93574192586
Dx      = 0.166739277081
Dy      = 0.0
Dxp     = -1.91513471748e-15
Dyp     = 0.0
mux     = 0.0
muy     = 0.0
nu_x    = 0.0
nu_y    = 0.0
E       = 0.0
s        = 0.0

In [5]:

# plot optical functions.
plot_opt_func(lat, tws, top_plot = ["Dx", "Dy"], legend=False, font_size=10)
plt.show()

# you also can use standard matplotlib functions for plotting
#s = [tw.s for tw in tws]
#bx = [tw.beta_x for tw in tws]
#plt.plot(s, bx)
#plt.show()

In [6]:

# you can play with quadrupole strength and try to make achromat
Q4.k1 = 1.18

# to make achromat uncomment next line
# Q4.k1 =  1.18543769836
# To use matching function, please see ocelot/demos/ebeam/dba.py 

# updating transfer maps after changing element parameters. 
lat.update_transfer_maps()

# recalculate twiss parameters 
tws=twiss(lat, nPoints=1000)

plot_opt_func(lat, tws, legend=False)
plt.show()

In [ ]: