Copyright 2019 CERN. This software is distributed under the terms of the GNU General Public Licence version 3 (GPL Version 3), copied verbatim in the file LICENCE.txt. In applying this licence, CERN does not waive the privileges and immunities granted to it by virtue of its status as an Intergovernmental Organization or submit itself to any jurisdiction.
BLonD (Beam Longitudinal Dynamics)
CERN code for the simulation of longitudinal beam dynamics in synchrotrons.
Repository: https://github.com/blond-admin/BLonD
Documentation: http://blond-admin.github.io/BLonD/
Project website: http://blond.web.cern.ch
- A gcc compiler with C++11 support (version greater than 4.8.4).
- An Anaconda distribution (Python 3 recommended).
- That's all!
- Download the latest mingw-w64 using this link: https://sourceforge.net/projects/mingw-w64/files/latest/download
- Run the downloaded executable.
- Make sure to select: Architecture: x86_64, Threads: posix and Exception: seh
- Select the installation location, e.g.:
"C:\Users\myname\mingw-64"
- Wait for the installation to complete, then add the following path to your User Environment Variable Path:
"C:\Users\myname\mingw-64\mingw64\bin"
- To validate the correct setup of gcc, open a command prompt and type:
gcc --version
. The first output line should contain the gcc version you just installed.
- Using the pip package manager:
$ pip install blond
If this fails try to:
- Clone the repository from github or download and extract the zip from https://github.com/blond-admin/BLonD/archive/master.zip.
- Navigate to the downloaded BLonD directory and run:
$ python setup.py install
If it still fails, navigate to the BLonD directory and run:
$ python setup.py compile
Then you have to use the PYTHONPATH variable or some other mechanism to point to the BLonD installation.
In the extremely rare occasion that it continues to fail, you can submit an issue and we will handle it ASAP.
- You are advised to install git in your system.
- Clone the repository or download and extract it.
- From within the BLonD directory run:
$ python blond/compile.py
- Adjust the PYTHONPATH to contain the path to the cloned repository.
- Run the unittests with pytest (may need to be installed first with pip install pytest):
$ pytest -v unittests
- Try to run some of the main files found in the examples:
$ python __EXAMPLES/main_files/EX_01_Acceleration.py $ python __EXAMPLES/main_files/EX_02_Main_long_ps_booster.py $ etc..
There are some easy ways to reduce the execution time of your simulation:
- Use the multi-threaded C library. To use it you have to add the -p flag when compiling the C library:
$ python blond/compile.py --parallel
- Enable processor specific compiler optimizations:
$ python blond/compile.py --flags='-march=native'
- If you are test-case is calling the synchrotron radiation tracking method, you can accelerate it by using the Boost library. To do so you have to:
Download Boost: https://www.boost.org/. Let's say the version you downloaded is boost_1_70.
Extract it, let's say in
/user/path/to/boost_1_70
.- Pass the boost installation path when compiling BLonD:
$ python blond/compile.py --boost=/user/path/to/boost_1_7_70/include
Check the following section about the FFTW3 library.
All the above can be combined.
- By default BLonD uses double precision calculations (float64). To change to single precision, for faster calculations, in the beginning of your mainfile you will have to add the code lines:
from blond.utils import bmath as bm bm.use_precision('single')
No other modifications are needed.
So far only the rfft()
, irfft()
and fftfreq()
routines are supported. fft_convolve()
to be added soon.
Windows:
Download and unzip the pre-compiled FFTW3 library. Link: ftp://ftp.fftw.org/pub/fftw/fftw-3.3.5-dll64.zip
Copy the
libfftw3-3.dll
under your python's distribution directory.Run the
blond/compile.py
with the flag--with-fftw
.If the FFTW3 library is not installed in one of the default directories, use the
--with-fftw-lib
and--with-fftw-header
to point to the directories where the shared library and header files are stored.- To use the supported routines, you need to call the function
use_fftw()
frombmath.py
: from blond.utils import bmath as bm bm.use_fftw() ... bm.rfft(...) bm.irfft(...) bm.rfftfreq(...)
- To use the supported routines, you need to call the function
Linux:
Download and compile the FFTW3 library. Link: http://www.fftw.org/fftw-3.3.8.tar.gz
Run the
blond/compile.py
with the flag:--with-fftw
.If the FFTW3 library is not installed in one of the default directories, use the
--with-fftw-lib
and--with-fftw-header
to point to the directories where the shared library and header files are stored.Optionally, you can enable one of the flags
--with-fftw-omp
or--with-fftw-threads
to use the multithreaded FFTs.- To use the supported routines, you need to call the function
use_fftw()
frombmath.py
: from blond.utils import bmath as bm bm.use_fftw() ... bm.rfft(...) bm.irfft(...) bm.rfftfreq(...)
- To use the supported routines, you need to call the function
Add the following lines in your ~/.bashrc, then source it:
# Environment variables definitions export LD_LIBRARY_PATH="$HOME/install/lib" export INSTALL_DIR="$HOME/install" export BLONDHOME="$HOME/git/BLonD" # User aliases alias mysqueue="squeue -u $USER" alias myscancel="scancel -u $USER" alias mywatch="watch -n 30 'squeue -u $USER'" # Module loads module load compiler/gcc7 module load mpi/mvapich2/2.3
Download and install anaconda3:
cd ~ mkdir -p ~/downloads cd downloads wget https://repo.continuum.io/archive/Anaconda3-2018.12-Linux-x86_64.sh bash Anaconda3-2018.12-Linux-x86_64.sh -b -p $HOME/install/anaconda3
Download and install fftw3 (with the appropriate flags):
cd ~ mkdir -p ~/downloads cd downloads wget http://www.fftw.org/fftw-3.3.8.tar.gz tar -xzvf fftw-3.3.8.tar.gz cd fftw-3.3.8 ./configure --prefix=$HOME/install/ --enable-openmp --enable-single --enable-sse2 --enable-avx --enable-avx2 --enable-fma --enable-avx-128-fma --with-our-malloc --disable-fortran --enable-shared make -j4 make install
install mpi4py with pip:
pip install mpi4py
clone this repo, compile the library and link with fftw3_omp
cd ~ mkdir -p git cd git git clone --branch=master https://github.com/blond-admin/BLonD.git cd BLonD python blond/compile.py -p --with-fftw --with-fftw-threads --with-fftw-lib=$INSTALL_DIR/lib --with-fftw-header=$INSTALL_DIR/include
adjust your main file as needed (described bellow).
example scripts to setup and run a parameter scan in the HPC Slurm cluster: https://cernbox.cern.ch/index.php/s/dS1hwr7E1eIdsne
- This statements in the beginning of the script:
from blond.utils import bmath as bm from blond.utils.mpi_config import worker, mpiprint bm.use_mpi()
- After having initialized the beam and preferably just before the start of the main loop:
beam.split()This line splits the beam coordinates equally among the workers.
- If there is code block that you want it to be executed by a single worker only, you need to surround it with this if condition:
if worker.isMaster: foo() ...
- If you need to re-assemble the whole beam back to the master worker you need to run:
beam.gather()
- Finally, in the end of the simulation main loop, you can terminate all workers except from the master with:
worker.finalize()
- To run your script, you need to pass it to mpirun or mpiexec. To spawn P MPI processes run:
$ mpirun -n P python main_file.py
- For more examples have a look at the __EXAMPLES/mpi_main_files/ directory.
- Simon Albright (simon.albright (at) cern.ch)
- Theodoros Argyropoulos (theodoros.argyropoulos (at) cern.ch)
- Konstantinos Iliakis (konstantinos.iliakis (at) cern.ch)
- Ivan Karpov (ivan.karpov (at) cern.ch)
- Alexandre Lasheen (alexandre.lasheen (at) cern.ch)
- Danilo Quartullo (danilo.quartullo (at) cern.ch)
- Joel Repond (joel.repond (at) cern.ch)
- Helga Timko (Helga.Timko (at) cern.ch)
Juan Esteban Muller
- the folder __TEST_CASES contains several main files which show how to use the principal features of the code;
- the __doc folder contains the source files for the documentation on-line;
- the various packages which constitute the code;
- setup_cpp.py is needed to compile all the C++ files present in the project; this file should be run once before launching any simulation. The compiler C++ GCC (at least version 4.8) is necessary.
- WARNINGS.txt contains useful information related to code usage.
- 2017-03-28 v1.19.0 - Several files have been rearranged and simplified
- 2017-02-10 v1.18.0 - Fixed an important bug in linear_interp_kick.cpp: before the acceleration kick was not applied if rf_kick_interp==TRUE in RingAndRFSection
- v1.17.0 - Numerical synchrotron frequency distribution added (TC12) - Possibility to compute multi-turn wake with acceleration (inimpedance.py) - fixed a bug in the periodicity routine (in tracker.py)
- 2016-10-24 v1.16.0 - MuSiC algorithm introduced, TC11 added, minor bugs fixed
- 2016-07-29 v1.15.1 - several upgrades and bug fixes
- 2016-06-23 v1.14.5 - RF modulation file added in llrf folder - documentation on-line for PSB phase loop added - setup_cython.py removed because not used
- 2016-06-21 v1.14.4 -