Accelerator, radiation and x-ray optics simulation framework

An Introduction to Ocelot

Ocelot is a multiphysics simulation toolkit designed for studying Free Electron Lasers (FEL) and storage ring-based light sources. Implemented in Python, Ocelot caters to researchers seeking the flexibility provided by high-level languages like Matlab and Python. Its core principle revolves around scripting beam physics simulations in Python, utilizing Ocelot's modules and extensive collection of Python libraries.

Users developing high-level control applications can accelerate development by using physics models from Ocelot and Python graphics libraries such as PyQt and PyQtGraph to create a GUI.

Developing machine learning (ML) applications for accelerators can also benefit from using Ocelot, as many popular ML frameworks are written in Python. Ocelot provides a seamless connection between physics and ML methods, making it easier to integrate physical accelerator simulators with machine learning algorithms.

Contents

1. Ocelot main modules
2. Ocelot installation
3. Tutorials

Ocelot main modules:

• Charged particle beam dynamics module (CPBD)
  • optics
  • tracking
  • matching
  • collective effects (description can be found here and here)
    • Space Charge (3D Laplace solver)
    • CSR (Coherent Synchrotron Radiation) (1D model with arbitrary number of dipoles).
    • Wakefields (Taylor expansion up to second order for arbitrary geometry).
  • MOGA (Multi Objective Genetics Algorithm) ref.
• Native module for spontaneous radiation calculation (some details can be found here and here)
• FEL calculations: interface to GENESIS and pre/post-processing
• Modules for online beam control and online optimization of accelerator performances. ref1, ref2, ref3, ref4.
  • This module is being developed in collaboration with SLAC. The module has been migrated to a separate repository (in ocelot-collab organization) for ease of collaborative development.

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 /demos/ folder and jupyter tutorials

Ocelot installation

Requirements

• Python 3.9+
• numpy version 1.8 or higher: http://www.numpy.org/
• scipy version 0.15 or higher: http://www.scipy.org/
• matplotlib version 1.5 or higher: http://matplotlib.org/
• h5py version 3.10 or higher, https://www.h5py.org

Optional, but highly recommended for speeding up calculations

• numexpr (version 2.6.1 or higher)
• pyfftw (version 0.10 or higher)
• numba

Orbit Correction module is required

• pandas

Installation

GitHub (for advanced python users)

Clone OCELOT from GitHub:

$ git clone https://github.com/ocelot-collab/ocelot.git

or download last release zip file. Now you can install OCELOT from the source:

$ python setup.py install

Anaconda Cloud (recommended)

The easiest way to install OCELOT is to use Anaconda cloud. In that case use command:

$ conda install -c ocelot-collab ocelot

PythonPath

Another way is download ocelot from GitHub

1. you have to download from GitHub zip file.

2. Unzip ocelot-master.zip to your working folder /your_working_dir/.

3. Add ../your_working_dir/ocelot-master 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/ocelot-master/ to PYTHONPATH. If variable PYTHONPATH does not exist, create it

   Variable name: PYTHONPATH

   Variable value: ../your_working_dir/ocelot-master/

   • Linux:

   $ export PYTHONPATH=/your_working_dir/ocelot-master:$PYTHONPATH
   

Tutorials

• Introduction. Tutorial N1. Linear optics
  • Linear optics. Double Bend Achromat (DBA). Simple example of usage OCELOT functions to get periodic solution for a storage ring cell.
• Tutorial N2. Tracking
  • Linear optics of the European XFEL Injector.
  • Tracking. First and second order.
  • Artificial beam matching - BeamTransform
• Tutorial N3. Space Charge
  • Tracking through RF cavities with SC effects and RF focusing.
• Tutorial N4. Wakefields
  • Tracking through corrugated structure (energy chirper) with Wakefields
• Tutorial N5. CSR
  • Tracking trough bunch compressor with CSR effect.
• Tutorial N6. RF Coupler Kick
  • Coupler Kick. Example of RF coupler kick influence on trajjectory and optics.
• Tutorial N7. Lattice design
  • Lattice design, twiss matching, twiss backtracking
• Tutorial N8. Physics process addition. Laser heater
  • Theory of Laser Heater, implementation of new Physics Process, track particles w/o laser heater effect.
• Tutorial N9. Tracking with parallel-plate corrugated structures
  • A simple accelerator with the electron beam formation system and an undulator to generate THz radiation.
• Tutorial N10. Simple accelerator based THz source
  • In this tutorial, a few examples for tracking with parallel-plate corrugated structures are shown. The wakefields model are based on analytical wakefield formulas for flat corrugated structures.

Photon field simulation

• PFS tutorial N1. Synchrotron radiation module.
  • Simple examples how to calculate synchrotron radiation with OCELOT Synchrotron Radiation Module.
• PFS tutorial N2. Coherent radiation module and RadiationField object.
• PFS tutorial N3. Reflection from imperfect highly polished mirror.
• PFS tutorial N4. Converting synchrotron radiation Screen object to RadiationField object for viewing and propagation.
• PFS tutorial N5: SASE estimation and imitation.

Appendixes

• Undulator matching.
  • brief theory and example in OCELOT
• Some useful OCELOT functions
  • Aperture, RK tracking
• Example of an accelerator section optimization
  • A simple demo of accelerator section optimization with a standard scipy numerical optimization method.

To launch "ipython notebook" or "jupyter notebook"

If you want to play with these tutorials they can be found in ocelot/demos/ipython_tutorials. Run the following commands in the command line:

$ ipython notebook

or

jupyter lab

Documentation

The API documentation can be build using sphinx. To do so, you have to clone the repository or download the zip file, as explained in the ocelot installation section. Then you can install all dependencies by running

python -m pip install -r docs/requirements.txt
python setup.py install

Now you can build the documentation by running

python setup.py build_sphinx

If these steps succeeded (yes, there are still very many errors and warnings during building the documentation), you can browse the HTML documentation by opening build/sphinx/html/index.html in your browser.

Disclaimer: The OCELOT code comes with absolutely NO warranty. The authors of the OCELOT do not take any responsibility for any damage to equipments or personnel injury that may result from the use of the code.