IBS - Intra Beam Scattering

C++ Library with PYBIND11 Python wrapper for IBS calculations, including an ODE model simulation.

• Free software: MIT license
• Documentation: https://ibslib.readthedocs.io.

Tutorial on Binder

Visit the link below for a live jupyter notebook with the turorial.

https://mybinder.org/v2/gh/tomerten/ibs/main?filepath=IBS%2Fdocs%2Fnotebooks%2FTutorial.ipynb

Requirements

For the installation:

• CMake >= 3.10.2
• GCC compiler
• Python >= 3.7.1
• Git - for the submodules

For the docs (see docs/requirements.txt - except doxygen):

• doxygen
• breathe
• sphinx-click
• click
• cookiecutter
• semantic-version
• matplotlib
• ipython
• nbsphinx
• ipykernel
• pandoc

Quick start

If you do not want to go through the trouble of installing everything on your local system, you can also use either Docker or Singularity containers.

$ git clone https://github.com/tomerten/IBS.git
$ cd IBS
$ docker build -t ibslib:latest .
$ sudo singularity build ibslib.sim ibslib.sdef

For quick access to the runode simulations (make sure input file and Twiss file are in the run directory):

$ ./ibslib.sim JSON_SIM_INPUT_FILE

For using docker have a look at the docker documentation on how to mount folders for using files from your local system. One interesting feature is running jupyter from within the container, giving you direct access to the tutorial notebook.

$ docker run -it --user 1000 -v DIR_TO_MOUNT:/home -p 8889:8888 ibslib:latest jupyter notebook --ip=0.0.0.0 --no-browser --allow-root

After this, open a browser and go to localhost:8889, copy the token from the terminal window and you are good to go. For the turorial navigate to IBS/docs/notebooks/Tutorial.ipynb. In the above case files from the DIR_TO_MOUNT directory will be in the home directory in the container. If you create a notebook and save it there it will also appear on your local (host) system.

Source Installation

The sources for ibs can be downloaded from the Github repo.

We recommend to install everything in a dedicated Conda environment.

$ conda create python=3.8 --name=ibslibenv
$ conda activate ibslibenv
$ conda install pip
$ pip install poetry

Clone the public repository and run the build_all.sh script:

$ git clone git://github.com/tomerten/ibs
$ cd ibs
$ bash build_all.sh

For more details see the installation guidelines on Installation documentation.

Build Docs

Building of the documentation is based on this article making use of Cmake, Doxygen, Breathe and Sphinx. It can be build locally by the following command:

$ bash build_docs.sh

Note

Make sure you have Doxygen and Pandoc installed.

To install Doxygen in a Conda environment:

$ conda install -c conda-forge doxygen

Features

• Read MADX Twiss module
• Numeric Functions Lib necessary for the IBS calculations, including necessary constants.
• Coulomb Log module
• Radiation Damping module
• Integration methods module (Simpson, Simpson Decade, Simpson Decade with scaling)
• IBS models
• ODE simulation module with CLI interface

Current Supported Models

• Piwinski smooth lattice approximation
• Piwinski Lattice element by element weighted
• Piwinski Lattice Modified taking some vertical effects into account
• Nagaitsev's high-energy approximation (standard Coulomb Log and with Tailcut)
• Bjorken-Mtingwa (standard Coulomb Log and with Tailcut)
• Conte-Martini (standard Coulomb Log and with Tailcut)
• Zimmerman (Madx - CERN note AB-2006-002) using TWINT and SIMPSONDECADE methods to perform the integration (standard Coulomb Log and with Tailcut).

Coublomb Log methods

• twclog - uses element by element twiss data
• twclogtail - uses element by element twiss data
• CoublombLog - uses ring averages
• TailCutCoulombLog - uses ring averages

Integration methods

• Simpson (standard implementation)
• SimpsonDecade - Simspon per decade for covering large spread in integration ranges (ususally 50 orders of magnitude difference between low and high)
• TWINT, SimsponDecade with scaling method

Radiation Damping

• Radiation Damping using smooth lattice approximation
• Radiation Damping element by element
• Equilibrium from pure radiation damping and exitation (taux, tauy, taus, exinf, eyinf, sigeoe2, sigsinf, jx, jy)
• Radiation losses per turn
• Critical omega, theta, photon energy

Numeric Functions

• Method to calculate standard accelerator quantities.
• Various methods related to RF calculations to derive longitudinal quantities necessary for the IBS algorithms.
• Numeric functions used by specific IBS models (fmohl, rds).

ODE

The tables below show examples of the output of the ODE method, applied to the BESSY II design lattice. For the examples below the stability threshold set to 1e-3 written to a csv file.