Installation

Prerequisites

Operating System

  • Linux (Debian/Ubuntu or any distribution with Conda support)

  • macOS

  • Windows 8 or higher (Git Bash required, see below)

Hardware

  • CPU: x86_64 processor

  • RAM: 4 GB minimum (8 GB recommended)

  • Disk: 50 GB free space

Software

  • Python 3.9 or higher

  • Git

  • An active internet connection (required for GNSS data retrieval)

Installation method — editable clone (required)

Important

RRINGG must be installed in editable mode (pip install -e .). This is the only supported installation method.

An editable install means Python points directly to the cloned src/ directory — no files are copied elsewhere. This has two consequences that are by design:

  1. You can modify src/config.py to change default processing parameters (GNSS source, plate code, fitting weights, etc.) and the changes take effect immediately on the next run. Note: the plane-fitting algorithm (IRLS vs RANSAC) is controlled exclusively by the --fitting / -fi CLI flag, not by config.py.

  2. You can update the tool with git pull without reinstalling.

See Configuration for a full description of every tunable parameter.

Step 1 — Clone the repository

Anonymous (HTTPS):

git clone https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-cycle/rringg.git
cd rringg

With a GitLab account (SSH):

git clone git@gricad-gitlab.univ-grenoble-alpes.fr:isterre-cycle/rringg.git
cd rringg

Specific branch (e.g. dev):

git clone git@gricad-gitlab.univ-grenoble-alpes.fr:isterre-cycle/rringg.git -b dev
cd rringg

Step 2 — Create the environment

RRINGG depends on GDAL Python bindings (osgeo), which require a pre-compiled binary compatible with the installed GDAL library. Mixing pip and conda in an ad-hoc way frequently causes version conflicts. Use the provided environment.yml to avoid them.

Recommended — from the environment file:

conda env create -f environment.yml
conda activate rringg-env

environment.yml installs Python 3.9.18, GDAL 3.5.3 (from conda-forge), and all pip dependencies from requirements.txt automatically. It resolves binary compatibility between GDAL and its Python bindings.

Fallback — manual Conda setup:

conda create -n rringg-env python=3.9.18
conda activate rringg-env
conda install -c conda-forge "gdal=3.5.3"
pip install -r requirements.txt

# Optional — alternative GDAL Python bindings (must match conda GDAL version exactly)
# pip install pygdal==3.5.3.11

Without Conda (not recommended):

python -m venv rringg-env
# Linux / macOS
source rringg-env/bin/activate
# Windows (Git Bash)
source rringg-env/Scripts/activate

pip install -r requirements.txt

Note

Installing without Conda requires a separately installed GDAL 3.5.x with matching Python bindings. Verify with:

python -c "from osgeo import gdal; print(gdal.__version__)"

Step 3 — Editable install

pip install -e .

This registers the src/ directory on the Python path and makes the rringg package importable from anywhere inside the rringg-env environment. Nothing is copied to site-packages.

Warning

Do not use pip install . (without -e). A regular install copies the source to site-packages, making src/config.py inaccessible for editing and breaking the update workflow.

Step 4 — Verify the installation

pytest tests/test_installation.py

All tests should pass. If a test fails, check that the Conda environment is active and that GDAL is correctly installed (Step 2).

Windows — preliminary setup

Before running the commands above on Windows, complete the following steps.

  1. Install Git Bash

    Download and install Git Bash. During installation, enable “Add Git Bash to PATH”.

  2. Install Miniconda

    Download and install the latest Miniconda for Windows.

  3. Activate the Conda base environment in Git Bash

    source activate base
# or, if the above fails:
conda activate base

Then follow Steps 1–4 above in Git Bash.

Updating RRINGG

Because the install is editable, updating is a single command:

cd rringg
git pull

No reinstallation is needed. If the environment.yml has changed (new or updated dependencies), recreate the environment:

conda env update -f environment.yml --prune

Modifying default parameters

All default processing parameters live in src/config.py. Because the installation is editable, editing this file changes the defaults for every subsequent run — no reinstallation required.

# Open the configuration file in your preferred editor
nano src/config.py        # or: vim, code, gedit, …

The parameters most commonly adjusted are:

Parameter

Location in config

What it controls

source

CFG.gnss.source

GNSS data provider: "NGL" or "EPOS"

plate

CFG.gnss.plate

ITRF tectonic plate code (e.g. "EURA", "NOAM")

weight_function

CFG.fitting.weight_function

Robust weight function for IRLS: "huber" or "tukey"

weighted

CFG.fitting.weighted

Enable Fisher-information station weighting

scale_bbox

CFG.spatial.scale_bbox

Bounding-box expansion factor before GNSS query

priority_centre

CFG.gnss.priority_centre

Preferred EPOS analysis centre (e.g. "UGA-CNRS")

See Configuration for the complete parameter reference.

Note

Parameters that are also exposed as CLI arguments (--plate, --fitting, --scale, etc.) can be overridden on a per-run basis without editing config.py. Edits to config.py change the defaults that apply when no CLI argument is supplied.

Running RRINGG after installation

After pip install -e ., the rringg command is available anywhere inside the active environment:

rringg --help

See Running RRINGG for the full command reference and workflow examples.