Licenza

Consulta le condizioni di licenza.


Note di rilascio


La lettura in streaming richiede le interfacce SRO di GEMC 0.5 e i plugin degli esperimenti ricompilati con la stessa installazione di GEMC. L’encoder JLAB di FT-Cal appartiene a clas12-systems; la sola installazione di pygemc non fornisce l’implementazione SRO nativa.

Gli esempi su vertice e angoli includono 11 schede di configurazione e grafici Analyzer già preparati. Usa GEMC 0.5 o versioni successive; i grafici della GUI richiedono Qt Charts. Le simulazioni batch e i controlli CSV funzionano anche senza Qt Charts.

Indice



Installare l’API Python


pygemc è disponibile su PyPI. Usa un ambiente virtuale per le installazioni dirette con pip:

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

I moduli Jupyter opzionali usati per l’esportazione VTK di PyVista possono essere installati con:

python -m pip install "pygemc[jupyter]"

Le dipendenze opzionali per l’analisi dei file ROOT possono essere installate con:

python -m pip install "pygemc[root]"

PyPI non installa l’eseguibile gemc, ma consente di creare e visualizzare geometrie o analizzare i risultati.


Scaricare una distribuzione binaria precompilata

I tarball binari contengono l’eseguibile gemc e gli esempi (ma non pygemc). Le build Linux sono disponibili per amd64 e arm64; la build macOS è nativa per Apple Silicon (arm64).

Controlla i Prerequisiti software per l’installazione binaria prima di estrarre il tarball.

Scegli prima una directory di installazione:

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

Poi usa i comandi della scheda corrispondente alla tua distribuzione Linux e all’architettura della CPU. Questo installerà GEMC e i file 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


Dopo l’installazione, carica il file di ambiente di GEMC con source. Aggiungi questa riga a .bashrc o .zshrc se vuoi che l’ambiente sia disponibile in ogni shell:

source /path/to/gemc/gemc.env

Esegui alcuni controlli per verificare l’installazione:

gemc -v
test_gdynamic_plugin_load
test_gdata_event_verbose


Compilare dai sorgenti

Per compilare GEMC avrai bisogno di Geant4. Consulta i Prerequisiti software e installazione di Geant4 per la compilazione di GEMC nell’appendice per l’elenco completo dei requisiti.


1. Ottenere i sorgenti

Scarica il codice:

Scarica l’ultima release:

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


2. Configurare la build e installare GEMC

Per compilare e installare GEMC viene usato il sistema di build Meson.

La fase di configurazione verificherà le dipendenze richieste e scaricherà le librerie esterne. Qui usiamo una directory build.

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

La fase di installazione compilerà e installerà GEMC. Qui usiamo -q per una build silenziosa.

meson install -C build -q

Facoltativamente, dopo l’installazione, esegui meson test -C build per testare la build di GEMC configurata.


Opzioni di build


Dopo l’installazione

Aggiungi queste righe al file di configurazione della tua shell (ad esempio ~/.bashrc o ~/.zshrc):

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

La seconda voce di PATH aggiunge l’ambiente virtuale Python incluso, così che python3 punti all’interprete dell’ambiente virtuale, rendendo disponibile import pygemc nei tuoi script.

Verifica il simulatore e gli strumenti Python installati con:

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


Sistemi di rivelatori CLAS12 dai sorgenti

I sistemi di rivelatori CLAS12 (clas12-systems) 0.3 si compilano con la stessa procedura Meson e non richiedono più un’installazione preesistente di GEMC. In un ambiente con il solo Geant4, per esempio un’immagine Docker di g4install, la build compila automaticamente GEMC dal sottoprogetto gemc e lo installa nello stesso prefisso, così la geometria dei rivelatori e i plugin possono essere installati interamente da zero. Solo Geant4 deve essere già presente (non viene mai compilato); GEMC viene cercato, nell’ordine, nel percorso esplicito -Duse-gemc-location=<dir>, tra le installazioni presenti tramite PATH/pkg-config e, infine, nel sottoprogetto compilato dai sorgenti.

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



Eseguire in un container Docker

Puoi usare Docker per eseguire GEMC. Le immagini disponibili sono elencate di seguito. Sono supportate sia arm64 sia amd64 (eccetto nelle immagini Arch Linux, disponibili solo per amd64 1).

Sistema operativo Versione GEMC Indirizzo del registry 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

Gli indirizzi qui sopra rimandano alle immagini su Docker Hub, pubblicate nel programma Docker-Sponsored Open Source, che consente pull anonimi illimitati. Sono copie della build di riferimento su GitHub Container Registry: i due registry hanno contenuti e tag identici. Per effettuare il pull da GHCR, sostituisci il prefisso docker.io/gemc/gemc: con ghcr.io/gemc/src: mantenendo lo stesso tag, ad esempio ghcr.io/gemc/src:dev-ubuntu-24.04.

Si consiglia di montare una directory locale tramite bind mount per salvare e conservare il tuo lavoro. A titolo di esempio, i comandi seguenti associano il percorso del container /mywork a ~/mywork e usano l’immagine ghcr.io/gemc/src:dev-almalinux-10.

immagini archlinux amd64.


Modalità batch

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


Interfaccia grafica nel browser

Imposta queste variabili di supporto per la sessione interattiva. Scegli la tua password:

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

Poi apri nel browser http://localhost:6080/vnc.html per accedere all’interfaccia grafica.


Eseguire con Apptainer

Gli host Linux possono usare apptainer (precedentemente singularity) per eseguire i container Docker. Puoi usarlo con le immagini Docker qui sopra. Funziona in modo simile a Docker, ma l’entrypoint deve essere caricato esplicitamente con source.

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

Poi:

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


Warning

L’interfaccia grafica, in particolare le finestre OpenGL, potrebbe non funzionare correttamente in Apptainer quando ti connetti tramite un host remoto.


Nota

Apptainer usa una directory di cache predefinita per memorizzare le immagini. Se si riempie, imposta la directory di cache e quella temporanea in una posizione con spazio su disco sufficiente. Per esempio, imposta sim_cache su un percorso con spazio sufficiente:

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

poi imposta queste variabili:

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

ed esegui di nuovo apptainer.




Appendice


Prerequisiti software per l’installazione binaria


Le installazioni da tarball binario richiedono solo i pacchetti di runtime necessari all’eseguibile gemc e gli strumenti usati per scaricare ed estrarre l’archivio. ROOT è volutamente escluso da questo elenco.


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


Prerequisiti software e installazione di Geant4 per la compilazione di GEMC




Comandi su una riga per installare pacchetti di base e dipendenze su MacOS e alcune distribuzioni Linux diffuse:


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 può usare qualsiasi installazione personalizzata di CLHEP/Xerces-C/Geant4, tuttavia consigliamo di usare il repository g4install per installare Geant4, poiché consente la coesistenza di più versioni di Geant4 e fornisce script di installazione.


Piattaforme supportate e testate




  1. Sui Mac con Apple Silicon aggiungi l’opzione --platform linux/amd64 al comando docker run per usare le ↩