Installation¶
Installing and using the Zgoubidoo Python library requires a working Python 3.7+ environment.
The easiest way is to proceed with conda to set it up. In case you already have a Python 3.7 environment available,
you can simply install Zgoubidoo with pip directly. Zgoubidoo has a relatively small number of
dependencies, and no non-Python dependencies, except of course for Zgoubi itself. Detailed step-by-step
instructions are provided in the following sections.
Compiling and installing Zgoubi¶
Zgoubi can be obtained from the official SourceForge repository, although we do not explicitely support the compilation and installation of Zgoubi with that method. Indeed, no platform-independent build system is provided and it is difficult to support compilation over a variety of platforms. A selection of ``Makefile``s is provided. In case one of them suits your needs, a brief description of the build process is given in the next section.
A non-official git repository, tracking the SVN repository (using git svn) is maintained in parallel with
Zgoubidoo. You can contact us to obtain access. That repository provides a build system using cmake, which allow to
compile over a variety of platforms and compilers.
In particular, the build process for recent versions of gfortran on Mac OS is actively supported. The dependencies
are cmake and gfortran. They can be installed using your package manager, brew on Mac OS works just fine.
The following steps are recommended on a Mac:
# Install cmake on Mac OS
brew install cmake
# Install gfortran on Mac OS
brew install gcc
# Clone the git repository in a source directory
git clone https://github.com/ulb-metronu/zgoubi.git zgoubi-source
cd zgoubi-source
git checkout develop
cd ..
mkdir zgoubi-build
cd zgoubi-build
cmake ../zgoubi-source
make
The Zgoubi executable is then available in the bin directory. No specific step is required to “install” Zgoubi, but
a symbolic link can be a good idea:
ln -s ./bin/zgoubi /usr/local/bin/zgoubi
Compiling Zgoubi from the official SourceForge repository¶
Zgoubi can be obtained from SourceForge (download or svn checkout). A Fortran compiler is required: both ifort
and gfortran are supported (‘Makefile’s are provided).
After the compilation the zgoubi executable will be available in the zgoubi directory. Depending on the Makefile
you use, zpop will also be built. zpop is not used by Zgoubidoo.
Zgoubidoo needs to be able to locate the zgoubi executable. The easiest way is to have it somewhere in your $PATH
so that which (via Python shutil.which) is able to find it. Alternatively, it is possible to provide the path
at runtime (see the zgoubidoo.Zgoubi class).
Obtaining Zgoubidoo¶
Zgoubidoo is hosted on github (see Zgoubidoo’s Github repository). To obtain the code using git do:
git clone https://github.com/chernals/zgoubidoo.git
The default branch (master) should be clean at all time, with all the development happening in the develop branch. It should thus be safe to pull from the master branch to get the latest version. Only the released and tagged versions are merged onto the master branch.
To stay on a released (tagged) revision:
git clone --branch 'tag_name' https://github.com/chernals/zgoubidoo.git
The releases CHANGELOG follows.
Note
- 2020.1 - Major stability improvements
Refactoring of multiple classes in georges-core (Kinematics and Sequence, among others);
Major clean up and testings of the elements classes;
Improvements in the plotting module.
- 2019.3 - Coherent support of the high-level ‘sequence’ API and synchrotron radiation
[FEATURE] A brand new ‘sequence’ API (see the ‘sequences’ module) supporting lattice description that are
code independent. They can be automatically loaded and converted from MAD-X Twiss files onto Zgoubi or MAD-X inputs; - [FEATURE] More complete Twiss computation module taking advantage of the survey and global reference frame for coordinates transformation. Twiss parameters are now correct also for strange lattices with arbitraty rotations; - [FEATURE] Now supports running MAD-X as well, with all the same nice functionalities. - [BUG FIXES] Many, many, many bug fixes;
- 2019.2 - Brand new support for concurrent execution of multiple Zgoubi’s instances
Full support for concurrent multiprocessing execution is provided;
Improvement capabilities for multi-dimensional parametric mappings;
Lots of bug fixes and documentation update.
- 2019.1 - First stable release.
See the announcement in the documentation.
- 2018.1 - First release!
Support all Zgoubi elements, altough some commands (in particular related to electric elements or spin tracking)
have never been tested; - Step-by-step computation of Twiss parameters (in a similar fashion to what pyzgoubi does) using 11 particules.
Creating a Python 3.7 environment with Conda¶
The Zgoubidoo repository contains a conda environment file that can be used to create a complete Python 3.7
environment suitable for Zgoubidoo:
cd path_to_zgoubidoo
conda env create --file environment.yml
or you can give a custom name to the environment with:
conda env create --file environment.yml --name your_custom_name
Installation Zgoubidoo using pip¶
The first step is to activate your Python 3.7 environment (only needed if you do not use a global
instalaltion of Python. On Mac OS if you use the Python brew installation you should already have Python 3.7
available from your path). With conda proceed like this:
conda activate py37
where py37 is the name of the environment created by default if you used the requirement.txt file as described above.
Zgoubidoo can then be installed using pip:
cd path_to_zgoubidoo
pip install .
Upgrading Zgoubidoo:
pip install . --upgrade
Alternatively if you intend to develop Zgoubidoo you can install it in editable mode:
pip install -e .
The second method allows any change to be reflected directly to your Zgoubidoo package (only a symlink is created in site-packages). This is the recommended way if you want to stay on the latest version of Zgoubidoo (development branch develop).
Using Zgoubidoo with Jupyter Notebook¶
Any installation of Jupyter would work as long as the Python 3.7 kernel from the conda installation can be selected.
For that it is best to install the extension nb_conda_kernels. The conda environment already contains a working
installation of jupyter with the conda extensions:
conda activate py37
jupyter notebook
# Or using Jupyter Lab
jupyter lab
From there you can create a new notebook and simply import Zgoubidoo:
import zgoubidoo