Licence

Consultez les conditions de la licence.


Notes de version


La lecture en continu nécessite les interfaces SRO de GEMC 0.5 et les plugins propres à l’expérience recompilés avec la même installation de GEMC. L’encodeur JLAB de FT-Cal appartient à clas12-systems ; installer pygemc seul ne fournit pas l’implémentation SRO native.

Les exemples de vertex et d’angles comprennent 11 cartes de pilotage et des tracés Analyzer préparés. Utilisez GEMC 0.5 ou une version ultérieure ; les tracés de l’interface graphique nécessitent Qt Charts. Les simulations par lots et les vérifications CSV de ces exemples fonctionnent également sans Qt Charts.

Table des matières



Installer l’API Python


pygemc est disponible sur PyPI. Utilisez un environnement virtuel pour les installations directes avec pip :

python3 -m venv ~/venv/pygemc
source ~/venv/pygemc/bin/activate
python -m pip install pygemc

Les modules Jupyter facultatifs utilisés pour l’export VTK de PyVista peuvent être installés avec :

python -m pip install "pygemc[jupyter]"

Les dépendances facultatives pour l’analyse de fichiers ROOT peuvent être installées avec :

python -m pip install "pygemc[root]"

L’installation depuis PyPI ne fournit pas l’exécutable gemc, mais permet de créer et visualiser des géométries ou d’analyser des résultats.


Télécharger une distribution binaire précompilée

Les archives binaires contiennent l’exécutable gemc et les exemples (mais pas pygemc). Les versions Linux sont disponibles pour amd64 et arm64 ; la version macOS est native pour Apple Silicon (arm64).

Vérifiez les prérequis logiciels pour l’installation binaire avant de décompresser l’archive.

Choisissez d’abord un répertoire d’installation :

gemc_home=/path/to/gemc
mkdir -p "$gemc_home"
cd "$gemc_home"

Utilisez ensuite les commandes de l’onglet correspondant à votre distribution Linux et à votre architecture CPU. Cela installera GEMC et les fichiers Geant4 data.

archive=gemc-dev-geant4-11.4.3-fedora-44-amd64.tar.gz
curl -L -o "$archive" "https://github.com/gemc/src/releases/download/dev/$archive"
tar -xzf "$archive" -C "$gemc_home" --strip-components=1
./install_geant4_data.sh


Après l’installation, chargez le fichier d’environnement de GEMC dans votre shell. Ajoutez cette ligne à .bashrc ou .zshrc si vous souhaitez que l’environnement soit disponible dans tous les shells :

source /path/to/gemc/gemc.env

Lancez quelques vérifications pour confirmer l’installation :

gemc -v
test_gdynamic_plugin_load
test_gdata_event_verbose


Compiler à partir des sources

Vous aurez besoin de Geant4 pour compiler GEMC. Consultez les prérequis logiciels et l’installation de Geant4 pour la compilation de GEMC dans l’annexe pour obtenir la liste complète des exigences.


1. Obtenir les sources

Téléchargez le code :

Téléchargez la dernière version :

git clone -c advice.detachedHead=false --branch 0.5 https://github.com/gemc/src
cd src


2. Configurer la compilation et installer GEMC

Le système de compilation Meson est utilisé pour compiler et installer GEMC.

La phase de configuration vérifie les dépendances requises et récupère les bibliothèques externes. Ici, nous utilisons un répertoire build.

meson setup build --prefix=/path/to/install/gemc

La phase d’installation compile et installe GEMC. Ici, nous utilisons -q pour une compilation silencieuse.

meson install -C build -q

Après l’installation, vous pouvez exécuter meson test -C build pour tester la compilation configurée de GEMC.


Options de compilation


Après l’installation

Ajoutez ces lignes à votre fichier de configuration du shell (par exemple ~/.bashrc ou ~/.zshrc) :

export PATH=/path/to/install/gemc/bin:/path/to/install/gemc/python_env/bin:$PATH

La deuxième entrée de PATH ajoute l’environnement virtuel Python fourni afin que python3 désigne l’interpréteur de cet environnement, ce qui rend import pygemc disponible dans vos scripts.

Vérifiez le simulateur et les outils Python installés avec :

gemc -v
gemc-system-template --help
gemc-analyzer --help


Systèmes de détecteurs CLAS12 à partir des sources

Les systèmes de détecteurs CLAS12 (clas12-systems) 0.3 se compilent selon la même procédure Meson et ne nécessitent plus de GEMC préinstallé. Dans un environnement ne disposant que de Geant4 — par exemple une image Docker g4install — la compilation construit automatiquement GEMC à partir du sous-projet gemc et l’installe dans le même préfixe, permettant ainsi d’installer la géométrie et les plugins des détecteurs en partant de zéro. Seul Geant4 doit déjà être présent (il n’est jamais compilé) ; GEMC est recherché dans l’ordre suivant : un emplacement explicite -Duse-gemc-location=<dir>, un GEMC déjà installé accessible via PATH/pkg-config, puis le sous-projet compilé à partir des sources.

git clone --depth=1 --branch 0.3 https://github.com/gemc/clas12-systems
cd clas12-systems
meson setup build --prefix="$PWD/install"   # builds GEMC too if none is installed
meson compile -C build
meson install -C build



Exécuter dans un conteneur Docker

Vous pouvez utiliser Docker pour exécuter GEMC. Les images disponibles sont listées ci-dessous. arm64 et amd64 sont pris en charge (sauf pour les images Arch Linux, disponibles uniquement en amd64 1).

Système d’exploitation Version de GEMC Adresse du registre arm64 amd64
AlmaLinux 10 dev ghcr.io/gemc/src:dev-almalinux-10 true true
ArchLinux latest dev ghcr.io/gemc/src:dev-archlinux-latest false true
Debian 13 dev ghcr.io/gemc/src:dev-debian-13 true true
Fedora 44 dev ghcr.io/gemc/src:dev-fedora-44 true true
Ubuntu 24.04 dev ghcr.io/gemc/src:dev-ubuntu-24.04 true true
Ubuntu 26.04 dev ghcr.io/gemc/src:dev-ubuntu-26.04 true true

Les adresses ci-dessus correspondent aux images Docker Hub, publiées dans le cadre du programme Docker-Sponsored Open Source, qui autorise les téléchargements anonymes illimités. Elles sont des copies de la compilation de référence du GitHub Container Registry : les deux registres proposent des contenus et des étiquettes identiques. Pour télécharger depuis GHCR, remplacez le préfixe docker.io/gemc/gemc: par ghcr.io/gemc/src: et conservez la même étiquette, par exemple ghcr.io/gemc/src:dev-ubuntu-24.04.

Il est recommandé de monter un répertoire local pour enregistrer et conserver votre travail. À titre d’exemple, les commandes ci-dessous associent le chemin du conteneur /mywork à ~/mywork et utilisent l’image ghcr.io/gemc/src:dev-almalinux-10.

images archlinux amd64.


Mode par lots

docker run -it --rm -v ~/mywork:/mywork ghcr.io/gemc/src:dev-almalinux-10 bash


Interface graphique dans le navigateur

Définissez ces variables pour faciliter la session interactive. Choisissez votre propre mot de passe :

VPORTS=(-p 6080:6080 -p 5900:5900)
VNC_PASS=(-e X11VNC_PASSWORD=change-me)
VNC_BIND=(-e VNC_BIND=0.0.0.0)
GEO_FLAGS=(-e GEOMETRY=1920x1200)

docker run -it --rm -v ~/mywork:/mywork $VPORTS $VNC_BIND $VNC_PASS $GEO_FLAGS ghcr.io/gemc/src:dev-almalinux-10

Ouvrez ensuite http://localhost:6080/vnc.html dans votre navigateur pour accéder à l’interface graphique.


Exécuter avec Apptainer

Les hôtes Linux peuvent utiliser apptainer (anciennement singularity) pour exécuter des conteneurs Docker. Vous pouvez l’utiliser avec les images Docker ci-dessus. Son fonctionnement est similaire à celui de Docker, mais le script du point d’entrée doit être chargé explicitement dans le shell.

apptainer exec --cleanenv --bind ~/mywork:/mywork docker://ghcr.io/gemc/src:dev-almalinux-10 bash

Puis :

source /usr/local/bin/docker-entrypoint.sh
gemc -v


Warning

L’interface graphique, en particulier les fenêtres OpenGL, peut ne pas fonctionner correctement dans Apptainer lorsque vous vous connectez via un hôte distant.


Note

Apptainer utilise un répertoire de cache par défaut pour stocker les images. S’il est plein, choisissez pour le cache et les fichiers temporaires un emplacement disposant de suffisamment d’espace disque. Par exemple, définissez sim_cache sur un emplacement disposant de suffisamment d’espace :

	export sif_cache=/path/to/$USER/cache

définissez ensuite ces variables :

	export APPTAINER_CACHEDIR=$sif_cache/apptainer-cache
	export APPTAINER_TMPDIR=$sif_cache/apptainer-tmp
	export TMPDIR=$sif_cache/apptainer-tmp

et relancez apptainer.




Annexe


Prérequis logiciels pour l’installation binaire


Les installations à partir d’archives binaires nécessitent uniquement les paquets d’exécution de gemc et les outils permettant de télécharger et de décompresser l’archive. ROOT est volontairement exclu de cette liste.


dnf install -y --allowerasing ca-certificates curl gzip tar expat sqlite-libs zlib \
libX11 libXext libXmu libXt mesa-libEGL mesa-libGL qt6-qtbase qt6-qtsvg qt6-qtcharts tbb


Prérequis logiciels et installation de Geant4 pour la compilation de GEMC




Commandes d’installation en une ligne pour les paquets de base et les dépendances sur macOS et certaines distributions Linux courantes :


dnf install -y --allowerasing git make cmake gcc-c++ gdb valgrind libxcrypt-devel \
expat-devel zlib zlib-devel mariadb-devel sqlite-devel python3-devel ninja-build \
mesa-libGL-devel mesa-libGLU-devel libX11-devel libXpm-devel libXft-devel \
libXt-devel libXmu-devel libXrender-devel xorg-x11-server-Xvfb xrandr \
bzip2 wget curl nano bash zsh hostname gedit environment-modules pv which \
psmisc procps mailcap net-tools rsync patch bash-completion python3-numpy \
xterm x11vnc openbox lxqt-panel dejavu-sans-mono-fonts \
qt6-qtbase-devel qt6-qtsvg qt6-qtsvg-devel qt6-qtcharts-devel \
root liblsan libasan libubsan libtsan tbb



Important

GEMC peut utiliser toute installation personnalisée de CLHEP/Xerces-C/Geant4, mais nous recommandons d’utiliser le dépôt g4install pour installer Geant4, car il permet la coexistence de plusieurs versions de Geant4 et fournit des scripts d’installation.


Plateformes prises en charge et testées




  1. Sur un Mac Apple Silicon, ajoutez l’option --platform linux/amd64 à la commande docker run pour utiliser les ↩