Georges is an open source project hosted on Github under the GNU General Public Licence (GPL) version 3.
The succint README is linked to and reproduced below. The complete documentation follows.
georges¶
Georges’ the lemur opinionated particle accelerator modeling Python package. Also a thin wrapper over MAD-X/PTC, BDSim and G4Beamline.
Design¶
The aim of this library is to unify the description and computation of particle accelerator beamlines for different tools (MAD-X, PTC, BDSim and G4Beamline at this stage) in a unique Python library.
The library design strongly follows conventions and typical uses of the Pandas library: beamlines are naturally described as Dataframes. A functional approach is also one of the design goal of the library, something which fits well with Pandas. A clear separation between the beamline data, the beamline computations (e.g. Twiss) and the computation context is achieved. Beamline data are immutable, the context (e.g. external parameters such as the energy, momentum offset, initial beam, etc.) is immutable and always passed explicitely as a parameter and the computational facilities are implemented follwing a modular and chainable functional approach, unifying the above mentioned aspects.
Beamlines are loaded, converted (if necessary) and then transformed using functions split in packages (one package per beam physics code, e.g. MAD-X or G4Geamline). Those functional packages are supported by a series of proxy classes for each external computation code.
Support tools are also provided, notably a plotting library (entirely based on Matplotlib) which provides plotting capabilities for various optics computation (beam envelope, Twiss parameters, etc.).
Georges’s documentation¶
The documentation is part of the Georges repository itself and is made available via _Readthedocs_. It is hosted at [georges.readthedocs.io](http://georges.readthedocs.io/).
Introduction¶
Usage¶
No attempt is made to support python versions earlier than CPython 3.5. Jython and alternative implementation have not been tested.
Physics module¶
georges.physics is a simple standalone helper module providing various relativistic conversion functions as well as range computations for protons in water.
It is automatically importe when the main georges module is imported.
Pull requests are encouraged, as the module growths it will be necessary to split it in autonomous pieces.
import georges
georges.physics.energy_to_beta(0.1)
georges.physics.range_to_energy(4.0)
The georges.physics.kinematics function allows rapid and easy conversion between the different kinematics quantities used in beam physics (kinetic energy, momentum, magnetic rigidity, relativistic gamma and beta) and to proton range in water (using the IEC60601 range in water conversion).
georges.physics.kinematics(energy=100)
{
'beta': 0.43244159571922342,
'brho': 1.5010379999999999,
'energy': 102.33086821870768,
'gamma': 1.109063106808982,
'momentum': 450,
'range': 8.0501247517130885
}
georges.physics.kinematics(gamma=1.2)
{
'beta': 0.5527707983925666,
'brho': 2.0760332515185556,
'energy': 187.65441625999995,
'gamma': 1.2,
'momentum': 622.3792889875873,
'range': 23.248200723538545
}
georges.physics.kinematics(beta=0.4)
{
'beta': 0.4,
'brho': 1.365929596629474,
'energy': 85.466688943097552,
'gamma': 1.0910894511799618,
'momentum': 409.49550809723888,
'range': 5.8362733414685106
}
georges.physics.kinematics(range=32)
{
'beta': 0.59219057901310057,
'brho': 2.3000819451857275,
'energy': 226.12911179644985,
'gamma': 1.2410059046872013,
'momentum': 689.54741674333184,
'range': 32
}
Authorship and citation¶
Citation¶
The reference paper for the George library is Software X (2018), in preparation.
Authors of papers including reference to or results obtained with Georges are encouraged to cite as follow:
C. Hernalsteens, R. Tesse, K. Andre,
@article{GEORGES_2018,
author = " C\'edric Hernalsteens and Robin Tesse and K\'evin Andr\'e ",
title = { {Georges}: xxxx },
pages = { 2171--2175 },
volume = { 13 },
month = { jul },
year = { 2018 },
journal = { Software X }
}
List of publications¶
- Some paper
- Another paper
Installation¶
The installation process to get Georges up and running is relatively simple: the whole library is ready to be installed with pip and with conda.
However, as the georges submodules (in particular the georges.manzoni tracking code) are optimized to work with the Intel distribution for Python, detailed installation instructions are provided to install :mod: georges with Conda. This is the recommended way for the installation.
The Georges’ git repository is hosted on Github and on Gitlab (IBA internal).
Obtaining the Georges source code with Git¶
Simply clone the repository:
git clone https://github.com/chernals/georges
Or internally from IBA (replace username with your SSO login):
git clone git@gitlab.sw.goiba.net:username/georges.git
You can either stay on the bleeding-edge master branch or you can checkout a release tag:
git checkout tags/2018.2
Dependencies¶
A coherent set of dependencies is listed in the Conda environment.txt file as well as in the setup.py file (for setuptools and pip). In this way, installation using either conda or pip is possible. Note that the pip requirement file requirements.txt contains a single dot ., which refers to the dependency list provided in the setup.py file.
A typical user should not worry about those dependencies: they are properly managed either with conda (see next section) or with pip (see below).
Installation with Anaconda and the Intel Python Distribution libraries¶
The installation procedure which follows creates a conda environment based on the Intel distribution for Python with all the necessary dependencies included and managed via conda itself (this ensures that all the dependencies are, if possible, based on the Intel channel and not managed with pip). Georges is then installed using pip from that conda environment. The dependencies are coherent and the pip installation of Georges will find all the dependencies listed in setup.py to be already installed in the conda environment.
Install Conda for your operating system, follow the instructions for
Obtain a copy of the git repository (see previous section)
Create a dedicated
condaenvironment (default name isipy3for Intel Python 3)cd path/to/georges conda env create -f environment.yml
Activate the environment
conda activate ipy3
Install Georges using
pipfrom thecondaenvironment# Typical installation pip install . # Install with pip in editable mode to get access to the modifications on the git repository pip install -e .
Georges can be subsequently updated by running
cd path/to/georges
git pull origin master
pip install --upgrade georges
Installation with pip¶
In case Georges needs to be installed with the system Python or a Python installation that is not managed with conda, the following simple steps can be followed to use pip directly. All the dependencies are then managed with pip. Please note that this will typically not enable the Intel optimization, resulting in slower code execution for the :mod: manzoni module.
Obtain a copy of the git repository (see previous section)
Install Georges with
pip:# Typical installation pip install . # Install with pip in editable mode to get access to the modifications on the git repository pip install -e .
Georges can be subsequently updated by running
cd path/to/georges
git pull origin master
pip install --upgrade georges
Using Georges with Jupyter Notebook¶
Georges can be used with Jupyter notebooks. No special care is needed.
If you installed Georges within the conda environment, simply run (note that it is not advised to put all your notebook within the git structure):
cd somewhere/good/for/notebooks
jupyter notebook
Georges distribution with Docker¶
TODO
A Docker image is made available to provide an easy access to a complete Jupyter Notebook + madx + georges environment.
Use the Dockerfile to build the image:
docker build .
or, to register the image as well:
docker build -t username/georges .
You can run a container with
docker run -it username/georges
then connect to http://localhost:8888 to access the Jupyter Notebook interface.
The image includes a complete Anaconda Python3 environment with the most common packages. The latest MAD-X development release is available in /usr/local/bin/madx.
Using and executing Georges¶
You can access the library by simply importing it:
import georges
This will include only the core components of Georges. The different Georges’ modules must be imported separately, depending on your needs:
import georges.madx import georges.bdsim import georges.manzoni import georges.plotting
See the examples below for a typical use case.
import georges from georges.plotting import * import georges.manzoni