Installation

You can install georges-core from PyPI with pip:

pip install georges-core

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

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

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

git checkout tags/2023.3

The installation process to get George’s core 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-core
poetry install --without dev,docs

Note

George’s-core uses python version >=3.9 and < 3.11

Georges-core can be subsequently updated by running the following:

git pull origin master
poetry update

Note

You can install a independent python environment with pyenv (https://github.com/pyenv/pyenv) and pyenv-virtualenv (https://github.com/pyenv/pyenv-virtualenv)

pyenv install 3.9-dev
pyenv virtualenv 3.9-dev py39

Then, activate your Python environment and install georges-core with Poetry

pyenv local py39
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-core is then installed using poetry from that conda environment.

1. Install Conda or Miniconda for your operating system.

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

3. Create a dedicated conda environment (default name is georges-core):

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

4. Activate the environment and update manually llvmlite:

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

5. Install Georges-core using poetry from the conda environment:

   poetry install --without dev,docs
   

Georges-core can be subsequently updated by running:

cd path/to/georges-core
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-core
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-core with Jupyter Lab

Georges-core 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-core distribution with Docker

A Docker image is made available to provide an easy access to a complete Jupyter Lab + georges-core environment.

Use the Dockerfile to build the image:

docker build

or, to register the image as well:

docker build -t georges-core -f Dockerfile .

You can run a container with:

docker run -it --rm --name georges_core -p 8899:8899 georges-core

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

import georges_core