Package: blond
Beam Longitudinal Dynamics Code (BLonD)Copyright NoticeCopyright 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.DescriptionCERN code for the simulation of longitudinal beam dynamics in
synchrotrons.Useful LinksRepository:https://gitlab.cern.ch/blond/BLonDDocumentation:https://blond-code.docs.cern.ch/Project website:http://blond.web.cern.chInstallationDependenciesPython 3.8 or above (Anaconda is recommended).(Optional) For better performance, a C++ (e.g.gcc,icc,clang, etc) compiler withC++11support.(Optional) C++ compiler installation instructionsWindowsDownload the latest mingw-w64 using this link:https://winlibs.com/#download-releaseExtract the downloaded zip/7-zip under e.g.C:\. You should now
see a directoryC:\mingw64.AddC:\mingw64\binin the PATH Environment Variable.Here you can
see how to do this in Windows
XP/Vista/7/8/10/11.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.LinuxUse your distribution's package manager to install the compiler of your choice. BLonD has been tested with:gcc(recommended),icc, andclang.Installation StepsInstalling BLonD from PyPI.Use thepippackage manager and simply run:pipinstallblondInstalling BLonD manually (advanced users/ developers).Clone the repository (withgit) or download and extract it.(Optional) From within the BLonD directory run:pythonblond/compile.pySee the complete list of optional command line arguments with:pythonblond/compile.py--helpThen install BLonD in edit mode with:pipinstall-e.Confirm proper installationA quick way to confirm the successfull installation is to run:python-c"from blond import test; test()"If you installed BLonD manually, you can in addition run the unittests withpytest. Thepytestpackage has to be installed first withpip. :pipinstallpytest
pytest-vunittestsNote that running all the unit-tests might take more than 20 minutes, depending on your system.You may also run some of the example main files found in the__EXAMPLESdirectory:python__EXAMPLES/main_files/EX_01_Acceleration.py
python__EXAMPLES/main_files/EX_02_Main_long_ps_booster.py
etc..Performance OptimizationsBLonD contains three computational backends, sorted in order of better performance:C++backend (Supports multi-threading and vectorization)Numbabackend(Supports multi-threading and vectorization)Python-only backend (No multi-threading or vectorization)The performance order also defines the order in which the backends will be used. If theC++blond libary has been compiled, then theC++backend will be used. Otherwise, if thenumbapackage is installed, the numba backend will be used. Finally, if neither condition is met, thepython-only backend will be used.To use theNumbabackend, you simply need to install the numba package withpip:pipinstallnumbaTo use theC++backend, follow the instructions provided in the sectionInstalling BLonD manually.In addition you may want to:Use the multi-threaded blondC++backend:pythonblond/compile.py--parallelEnable processor specific compiler optimizations:pythonblond/compile.py--parallel--optimizeIf 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:pythonblond/compile.py--boost=/user/path/to/boost_1_7_70Check the following section about the FFTW3 library.All the above can be combined, i.e.:pythonblond/compile.py--parallel--optimize--boost=...Changing the floating point number datatypeBy 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 following code lines:fromblond.utilsimportbmathasbmbm.use_precision('single')Use the FFTW3 library for the FFTsSo far only therfft(),irfft()andfftfreq()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.zipCopy thelibfftw3-3.dllunder your python's distribution
directory.Run theblond/compile.pywith the flag--with-fftw.If the FFTW3 library is not installed in one of the default
directories, use the--with-fftw-liband--with-fftw-headerto point to the directories where the shared library and header
files are stored.To use the supported routines, you need to call the functionuse_fftw()frombmath.py:fromblond.utilsimportbmathasbmbm.use_fftw()...bm.rfft(...)bm.irfft(...)bm.rfftfreq(...)Linux:Download and compile the FFTW3 library. Link:http://www.fftw.org/fftw-3.3.8.tar.gzRun theblond/compile.pywith the flag:--with-fftw.If the FFTW3 library is not installed in one of the default
directories, use the--with-fftw-liband--with-fftw-headerto point to the directories where the shared library and header
files are stored.Optionally, you can enable one of the flags--with-fftw-ompor--with-fftw-threadsto use the multithreaded FFTs.To use the supported routines, you need to call the functionuse_fftw()frombmath.py:fromblond.utilsimportbmathasbmbm.use_fftw()...bm.rfft(...)bm.irfft(...)bm.rfftfreq(...)Using the multi-node (MPI) implementationSet-up InstructionsAdd the following lines in your ~/.bashrc, then source it:# Environment variables definitionsexportLD_LIBRARY_PATH="$HOME/install/lib"exportINSTALL_DIR="$HOME/install"exportBLONDHOME="$HOME/git/BLonD"# User aliasesaliasmysqueue="squeue -u$USER"aliasmyscancel="scancel -u$USER"aliasmywatch="watch -n 30 'squeue -u$USER'"# Module loadsmoduleloadcompiler/gcc7
moduleloadmpi/mvapich2/2.3Download and install anaconda3:cd~
mkdir-p~/downloadscddownloads
wgethttps://repo.continuum.io/archive/Anaconda3-2018.12-Linux-x86_64.sh
bashAnaconda3-2018.12-Linux-x86_64.sh-b-p$HOME/install/anaconda3Download and install fftw3 (with the appropriate flags):cd~
mkdir-p~/downloadscddownloads
wgethttp://www.fftw.org/fftw-3.3.10.tar.gz
tar-xzvffftw-3.3.10.tar.gzcdfftw-3.3.10
./configure--prefix=$HOME/install/--enable-openmp--enable-single--enable-avx--enable-avx2--enable-fma--with-our-malloc--disable-fortran--enable-shared
make-j4
makeinstall
./configure--prefix=$HOME/install/--enable-openmp--enable-avx--enable-avx2--enable-fma--with-our-malloc--disable-fortran--enable-shared
make-j4
makeinstallinstall mpi4py with pip:pipinstallmpi4pyclone this repo, compile the library and link with fftw3_ompcd~
mkdir-pgitcdgit
gitclone--branch=masterhttps://github.com/blond-admin/BLonD.gitcdBLonD
pythonblond/compile.py-p--with-fftw--with-fftw-threads--with-fftw-lib=$INSTALL_DIR/lib--with-fftw-header=$INSTALL_DIR/includeadjust 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/shqtotwyn4rm8wsChanges required in the main file for MPIThis statements in the beginning of the script:fromblond.utilsimportbmathasbmfromblond.utils.mpi_configimportWORKER,mpiprintbm.use_mpi()After having initialized the beam and preferably just before the
start of the main loop:# This line splits the beam coordinates equally among the workers.beam.split()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:ifWORKER.is_master: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 tompirunormpiexec. To spawn P MPI processes run:mpirun-nPpythonmain_file.pyFor more examples have a look at the __EXAMPLES/mpi_main_files/
directory.Using the GPU backendSetup InstructionsInstallCUDA:https://developer.nvidia.com/cuda-downloadsInstall theCuPylibrary:https://docs.cupy.dev/en/stable/install.htmlTo verify your installation open a python terminal and execute the
following scriptimportcupyascpimportnumpyasnpa=cp.array(np.zeros(1000,np.float64))To compile the CUDA files execute blond/compile.py and add the flag
--gpu. The Compute Capability of your GPU will be automatically
detected:pythonblond/compile.py--gpuChanges required in the main file for GPURight before your main loop you need to add:fromblond.utilsimportbmathasbm# change some of the basic functions to their GPU equivalentbm.use_gpu()Also for every object you are using in your main loop that is in the
following list:GPU objectsBeamProfileRingAndRFTrackerTotalInducedVoltageInducedVoltageTimeInducedVoltageFreqInductiveImpedanceInducedVoltageResonatorRFStationBeamFeedbackyou need to call theirto_gpu()method. The following is a typical
example from the __EXAMPLES/gpu_main_files/EX_01_Acceleration.py
mainfile.# Define Objectsbeam=Beam(ring,N_p,N_b)profile=Profile(beam,CutOptions(n_slices=100),FitOptions(fit_option='gaussian'))# Initialize gpubeam.to_gpu()profile.to_gpu()If an object of this list has a reference inside a different one you
don't need to use theto_gpu()for the referenced object. In the
previous example, we don't need to callbeam.to_gpu()sincebeamis
referenced inside theprofile. The same would apply in aTotalInducedVoltageobject and the objects in itsinduced_voltage_list.DevelopersSimon 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)Juan Esteban Muller (JuanF.EstebanMuller (at) ess.eu)Danilo Quartullo (danilo.quartullo (at) cern.ch)Joel Repond (joel (at) repond.ch)Markus Schwarz (markus.schwarz (at) kit.edu)Helga Timko (Helga.Timko (at) cern.ch)Structurethe folder __EXAMPLES 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 are under the blond
directory;blond/compile.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.