Installation
We assume that you have a recent python installation (python 3.8+). It this is not the case you can make one following the dedicated section on how to get a miniforge installation.
Basic installation
The Xsuite packages can be installed using pip. We recommend installing Xsuite in a conda environment.
pip install xsuite
This installation allows using Xsuite on CPU. In order to perform tracking on CPU,
a C compiler needs to be installed on the system: when using conda, this is provided
by the compilers
package (conda install compilers
). To use Xsuite on GPU,
with the cupy and/or pyopencl you need to install the corresponding packages,
as described in the dedicated section.
If you are working on a Windows machine, Xsuite can be installed under
Windows Subsystem for Linux using the same instructions as for a vanilla Linux
machine. To install WSL, follow the steps outlined by Microsoft
(at the time of writing it suffices to run wsl --install
in an administrator
PowerShell or CMD prompt and follow the instructions).
After the installation, you can choose to precompile some often-used kernels, in order to reduce the waiting time spent on running the simulations later on. This can be accomplished simply by running the following command:
xsuite-prebuild
Developer installation
If you need to develop Xsuite, you can clone the packages from GitHub and install them with pip in editable mode:
git clone https://github.com/xsuite/xobjects
pip install -e xobjects
git clone https://github.com/xsuite/xdeps
pip install -e xdeps
git clone https://github.com/xsuite/xpart
pip install -e xpart
git clone https://github.com/xsuite/xtrack
pip install -e xtrack
git clone https://github.com/xsuite/xfields
pip install -e xfields
This installation allows using Xsuite on CPU. To use Xsuite on GPU, with the cupy and/or pyopencl you need to install the corresponding packages, as described in the dedicated section.
If all of the optional dependencies have also been installed, we can
verify our installation. To install test dependencies for an xsuite
package, one can replace the pip install -e some_package
commands in
the above snippet with pip install -e 'some_package[tests]'
. Once
the test dependecies are also installed, we can run the tests to check
if xsuite works correctly:
cd ..
PKGS=(xobjects xdeps xpart xtrack xfields)
for PKG in ${PKGS[@]}; do
python -m pytest xsuite/$PKG/tests
done
Optional dependencies
MAD-X and cpymad
To import MAD-X lattices you will need the cpymad package, which can be installed as follow:
pip install cpymad
Sixtracktools
To import lattices from a set of sixtrack input files (fort.2, fort.3, etc.) you will need the sixtracktools package, which can be installed as follow:
git clone https://github.com/sixtrack/sixtracktools
pip install -e sixtracktools
PyHEADTAIL
To use the PyHEADTAIL interface in Xsuite, PyHEADTAIL needs to be installed:
git clone https://github.com/pycomplete/pyheadtail
pip install cython h5py
pip install -e pyheadtail
Other useful packages
pip install tqdm
will enable progress bars in Xsuite in CLI and notebookspip install cython
to enablexsuite-prebuild
functionalitypip install matplotlib
for plotspip install xplt
is a plotting library for Xsuite and similar accelerator physics toolspip install jupyter ipympl
to be able to create and open notebooks with interactive graphspip install ipython
for a better Python interactive CLIpip install pytest-xdist
extends pytest with an-n N
option that can be used to run tests onN
corespip install gitpython click gh
needed for various Xsuite-developer related tasks
GPU/Multithreading support
In the following section we describe the steps to install the two supported GPU platforms, i.e. cupy and pyopencl, as well as the multithreading library OpenMP.
Installation of cupy
In order to use the cupy context, the cupy package needs to be installed.
In Anaconda or Miniconda/Miniforge (if you don’t have Anaconda or Miniconda/Miniforge, see dedicated section on how to get a miniforge installation)
this can be done as follows:
conda install mamba -n base -c conda-forge
pip install cupy-cuda11x
mamba install cudatoolkit=11.8.0
Installation of PyOpenCL
In order to use the pyopencl context, the PyOpenCL package needs to be installed. In Anacoda or Miniconda/Miniforge this can be done as follows:
conda config --add channels conda-forge # not needed for Miniforge
conda install pyopencl
Check that there is an OpenCL installation in the system:
ls /etc/OpenCL/vendors
Make the OpenCL installation visible to pyopencl:
conda install ocl-icd-system
For the PyOpenCL context we will need the gpyfft and the clfft libraries. For this purpose we need to install cython.
pip install cython
Then we can install clfft.
conda install -c conda-forge clfft
We locate the library and headers here:
$ ls ~/miniforge3/pkgs/clfft-2.12.2-h83d4a3d_1/
# gives: include info lib
(Or locate the directory via find $(dirname $(dirname $(type -P conda)))/pkgs -name "clfft*" -type d
.)
We obtain gpyfft from github:
git clone https://github.com/geggo/gpyfft
and we install gpyfft with pip providing extra flags as follows:
pip install --global-option=build_ext --global-option="-I/home/giadarol/miniforge3/pkgs/clfft-2.12.2-h83d4a3d_1/include" --global-option="-L/home/giadarol/miniforge3/pkgs/clfft-2.12.2-h83d4a3d_1/lib" gpyfft/
Alternatively (if the command above does not work) we can edit the setup.py
of gpyfft to provide the right paths to your clfft installation (and potentially the OpenCL directory of your platform):
if 'Linux' in system:
CLFFT_DIR = os.path.expanduser('~/miniforge3/pkgs/clfft-2.12.2-h83d4a3d_1/')
CLFFT_LIB_DIRS = [r'/usr/local/lib64']
CLFFT_INCL_DIRS = [os.path.join(CLFFT_DIR, 'include'), ] # remove the 'src' part
CL_INCL_DIRS = ['/opt/rocm-4.0.0/opencl/include']
And install gpyfft locally.
pip install -e gpyfft/
Installation of OpenMP
If using a Mac (and/or the Clang compiler), inside of your conda environment run
conda install llvm-openmp
. On Linux, the same functionality (for GCC) is
provided by conda install libgomp
.
Install Miniforge
If you don’t have a miniconda or miniforge installation, you can quickly get one ready for xsuite installation with the following steps. A miniforge installation is strongly recommended against a miniconda installation as miniforge uses by default the “conda-forge” channel while miniconda uses the “default” channel (https://repo.anaconda.com/pkgs/). While the “default” channel can require a paid license depending on its usage, the “conda-forge” channel is free for all to use (see https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/channels.html).
Note
The current versions of miniconda ship with the mamba command, which is a much faster reimplementation of conda written in C++. It can also be used.
On Linux
cd ~
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh
source miniforge3/bin/activate
pip install numpy scipy matplotlib pandas ipython pytest
On MacOS
We recommend installing Xsuite inside a conda environment:
cd ~
curl -OL https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-$(uname -m).sh
bash Miniforge3-MacOSX-$(uname -m).sh
source miniforge3/bin/activate
conda create -n xsuite_env python=3.11 # or your preferred version
conda activate xsuite_env
conda install compilers
Advanced information for developers
Building MAD-X and cpymad from source (tested with macOS)
First we build MAD-X
and cpymad
(largely following the
recommendations found
here and
here):
conda install compilers cmake
git clone https://github.com/MethodicalAcceleratorDesign/MAD-X
pip install --upgrade cmake cython wheel setuptools delocate
mkdir MAD-X/build && cd MAD-X/build
cmake .. \
-DCMAKE_POLICY_DEFAULT_CMP0077=NEW \
-DCMAKE_POLICY_DEFAULT_CMP0042=NEW \
-DCMAKE_OSX_ARCHITECTURES=arm64 \
-DCMAKE_C_COMPILER=clang \
-DCMAKE_CXX_COMPILER=clang++ \
-DCMAKE_Fortran_COMPILER=gfortran \
-DBUILD_SHARED_LIBS=OFF \
-DMADX_STATIC=OFF \
-DCMAKE_INSTALL_PREFIX=../dist \
-DCMAKE_BUILD_TYPE=Release \
-DMADX_INSTALL_DOC=OFF \
-DMADX_ONLINE=OFF \
-DMADX_FORCE_32=OFF \
-DMADX_X11=OFF
# Verify in the output of the above command that libraries
# for BLAS and LAPACK have been found. For this, you may need
# the macOS SDK, installable with `xcode-select --install`.
cmake --build . --target install
cd ../..
export MADXDIR="$(pwd)"/MAD-X/dist
git clone https://github.com/hibtc/cpymad.git
cd cpymad
export CC=clang
python setup.py build_ext -lblas -llapack
python setup.py bdist_wheel
delocate-wheel dist/*.whl
pip install dist/cpymad-*.whl
# Optionally, verify the installation of cpymad:
pip install pandas pytest
python -m pytest test
Rosetta installation (x86 emulation on Apple Silicon)
Install miniforge as above, and then create an x86 conda environment, like so:
CONDA_SUBDIR=osx-64 conda create -n xsuite-x86 python=3.10
conda activate xsuite-x86
conda config --env --set subdir osx-64
conda install compilers
Note
You may get some warnings similar to
activate_clang:69: read-only file system: /meson_cross_file.txt'
.
These may be ignored.
After carrying out the above steps, you can install xsuite using the usual commands, following either the basic or a developer installation guide, as given at the top of this page.