Installation#

For development purposes you can copy the source code on your computer. georges is hosted on Github and can be downloaded using the following:

git clone https://github.com/ULB-Metronu/georges.git

You can stay on the bleeding-edge master branch or you can checkout a release tag:

git checkout tags/2024.2

The installation process to get George’s running is relatively simple: the whole library is ready to be installed with Poetry. However, depending your configuration, you can use a conda environment based on the Intel distribution.

Dependencies#

A coherent set of dependencies is listed in the pyproject.toml file (section tool.poetry.dependencies) A typical user should not worry about those dependencies: they are correctly managed either with poetry

Installation using Poetry#

Assuming you have Poetry and Python installed on your system, go to the location of the library and simply use these commands:

cd path/to/georges
poetry install --without dev,docs

Note

George’s uses python version >=3.8.1 and < 3.11

Georges can be subsequently updated by running the following:

git pull origin master
poetry update

Note

You can install a independent python environment with pyenv and pyenv-virtualenv

pyenv install 3.10-dev
pyenv virtualenv 3.10-dev py310

Then, activate your Python environment and install georges with Poetry

pyenv local py310
poetry install --without dev,docs

Conda environment#

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. georges is then installed using poetry from that conda environment.

1. Install Conda or Miniconda for your operating system.

Obtain a copy of the git repository (see previous section)

Create a dedicated conda environment (default name is georges):

cd path/to/georges
conda env create -f environment.yml

Activate the environment and update manually llvmlite:

conda activate georges
pip install -I --force-reinstall llvmlite

Install georges using poetry from the conda environment:
```
poetry install --without dev,docs
```

georges can be subsequently updated by running:

cd path/to/georges
git pull origin master
poetry update

To ensure the installation with the Intel distribution is correctly made, you should run the commands without errors:

conda activate georges
python
import numpy.random_intel

In table below, we summarize the performances between numpy.random and numpy.random_intel. We compute the time to generate a Gaussian distribution with 1e8 particles:

res = generator([0, 0, 0, 0, 0],
        np.array(
            [
                [1, 0, 0, 0, 0],
                [0, 1, 0, 0, 0],
                [0, 0, 1, 0, 0],
                [0, 0, 0, 1, 0],
                [0, 0, 0, 0, 1],
            ],
        ),
        int(1e8),
    )

Performances comparison between numpy and numpy.intel#
Generator	Time (s)
numpy.random.multivariate_normal	59
numpy.random_intel.multivariate_normal	31

Using Georges with Jupyter Lab#

Georges can be used with Jupyter lab. No special care is needed, and you can simply run (note that it is not advised to put all your notebook within the git structure):

cd somewhere/good/for/notebooks
jupyter-lab

Georges distribution with Docker#

A Docker image is made available to provide an easy access to a complete Jupyter Lab + georges environment. To pull the Docker image, the user must first create a Personal Access Token as described in the Github Documentation

Docker image from Github#

The docker image can be pulled from Github using:

docker pull ghcr.io/ulb-metronu/georges:master

Docker image from scratch#

Use the Dockerfile in Georges’s repository to build the image:

docker build

or, to register the image as well:

docker build -t georges -f Dockerfile .

Run Docker#

You can run a container with:

docker run -it --rm --name georges -p 8899:8899 ${IMAGE_ID}

then connect to http://127.0.0.1:8899 to access the Jupyter Lab interface and type:

import georges

Note

You can tag the image using the following command:

docker image tag ${IMAGE_ID} georges
docker run -it --rm --name georges -p 8899:8899 georges