Licence

Consultez les conditions de licence.


Notes de version


La lecture en continu (streaming readout) nécessite les interfaces SRO de GEMC 0.5 ainsi que les plugins propres à l’expérience recompilés avec la même installation de GEMC. L’encodeur JLAB de FT-Cal fait partie de 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 graphiques Analyzer préparés. Utilisez GEMC 0.5 ou une version ultérieure ; les graphiques 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.

À venir dans la prochaine version : les outils Qt Linguist compilent les catalogues de traduction de l’interface graphique pendant la compilation ; les données de traduction Qt traduisent les boîtes de dialogue standard. Les commandes d’installation de paquets ci-dessous incluent ces deux éléments. Qt fourni par Homebrew comprend ces outils et ces catalogues. La langue de l’interface graphique est détectée automatiquement ; l’option facultative -language=<code> permet de la choisir explicitement.

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 de visualiser des géométries ou d’analyser des résultats.


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

Les archives binaires tar 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).

Veillez à consulter 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"

Ensuite, utilisez les commandes de l’onglet correspondant à votre distribution Linux et à l’architecture de votre processeur. 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 le shell courant. Ajoutez cette ligne à .bashrc ou .zshrc pour que l’environnement soit disponible dans chaque shell :

source /path/to/gemc/gemc.env

Exécutez 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 connaître la liste complète des prérequis.


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érifiera les dépendances requises et récupérera les bibliothèques externes. Ici, nous utilisons un répertoire build.

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

La phase d’installation compilera et installera 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 GEMC avec la configuration choisie.


Options de compilation


Après l’installation

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

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

La seconde 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 inclut automatiquement GEMC à partir du sous-projet gemc et l’installe dans le même préfixe, ce qui permet d’installer la géométrie des détecteurs et les plugins entièrement à partir de zéro. Seul Geant4 doit déjà être présent (il n’est jamais compilé) ; GEMC est recherché, dans l’ordre, à l’emplacement explicitement indiqué par -Duse-gemc-location=<dir>, parmi les installations déjà disponibles via PATH/pkg-config, puis dans 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

À venir dans la prochaine version : lors de la compilation avec un GEMC déjà installé, la procédure de compilation de CLAS12 installe ou met également à jour pygemc et ses outils en ligne de commande sous python_env, selon la même organisation que l’installation autonome de GEMC.



Exécuter dans un conteneur Docker

Vous pouvez utiliser Docker pour exécuter GEMC. Les images disponibles sont répertoriées ci-dessous. Les architectures arm64 et amd64 sont prises en charge (sauf pour les images Arch Linux, disponibles uniquement pour 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 désignent les images Docker Hub, publiées dans le cadre du programme Docker-Sponsored Open Source, qui autorise un nombre illimité de téléchargements anonymes. Ces images sont des copies de référence de celles produites sur GitHub Container Registry : les deux registres proposent des contenus et des étiquettes identiques. Pour les télécharger depuis GHCR, remplacez le préfixe docker.io/gemc/gemc: par ghcr.io/gemc/src: en conservant 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’illustration, 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. Il fonctionne de manière similaire à Docker, mais le script du point d’entrée doit être chargé explicitement dans le shell courant.

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

Ensuite :

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.


Remarque

Apptainer utilise un répertoire de cache par défaut pour stocker les images. S’il est plein, placez le cache et les répertoires temporaires à un emplacement disposant de suffisamment d’espace disque. Par exemple, faites pointer sim_cache vers 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 par archive binaire ne nécessitent que les paquets d’exécution requis par l’exécutable gemc et les outils permettant de télécharger et de décompresser l’archive. ROOT est délibérément 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 qt6-qttranslations 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 quelques 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 \
qt6-qttools-devel qt6-qttranslations \
root liblsan libasan libubsan libtsan tbb



Important

GEMC peut utiliser n’importe quelle 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 ↩