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; installare solo pygemc non fornisce l’implementazione SRO nativa.

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

In arrivo con il prossimo rilascio: gli strumenti Qt Linguist compilano i cataloghi linguistici della GUI durante la build; i dati di traduzione di Qt localizzano le finestre di dialogo standard. I comandi per i pacchetti qui sotto includono entrambi. Qt di Homebrew fornisce questi strumenti e cataloghi. La lingua della GUI viene rilevata automaticamente e può essere impostata manualmente con l’opzione -language=<code>.

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]"

L’installazione da PyPI non include 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).

Assicurati di controllare 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. Aggiungi questa riga a .bashrc o .zshrc se vuoi rendere l’ambiente 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 l’installazione di Geant4 per la build di GEMC nell’appendice per l’elenco completo dei requisiti.


1. Ottenere i sorgenti

Scarica il codice:

Scarica l’ultimo rilascio:

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


2. Configurare la build e installare GEMC

Il sistema di build Meson viene usato per compilare e installare GEMC.

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, in modo che python3 venga risolto nell’interprete dell’ambiente virtuale, rendendo import pygemc disponibile nei tuoi script.

Controlla il simulatore installato e gli strumenti Python 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, ad 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, nella posizione esplicita -Duse-gemc-location=<dir>, tra le installazioni già disponibili tramite PATH/pkg-config e infine nel sottoprogetto da compilare 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

In arrivo con il prossimo rilascio: quando si compila usando un’installazione esistente di GEMC, la build CLAS12 installa o aggiorna anche pygemc e i suoi strumenti da riga di comando sotto python_env, rispecchiando la struttura delle directory dell’installazione autonoma di GEMC.



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 per le immagini Arch Linux, disponibili solo per amd64 1).

OS Versione GEMC Indirizzo del registro 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 si riferiscono alle immagini su Docker Hub, pubblicate nell’ambito del programma Docker-Sponsored Open Source, che consente pull anonimi illimitati. Sono repliche della build di riferimento su GitHub Container Registry: i due registri contengono 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.

È consigliato montare una directory locale per salvare e conservare il tuo lavoro. A titolo illustrativo, i comandi qui sotto 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 per facilitare l’uso della sessione interattiva. Scegli una password personale:

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 il browser all’indirizzo http://localhost:6080/vnc.html per accedere all’interfaccia grafica.


Eseguire con Apptainer

Gli host Linux possono usare apptainer (precedentemente singularity) per eseguire container Docker. Puoi usarlo con le immagini Docker qui sopra. Funziona in modo simile a Docker, ma lo script di avvio deve essere caricato esplicitamente nella shell.

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 colleghi tramite un host remoto.


Nota

Apptainer usa una directory di cache predefinita per archiviare le immagini. Se si riempie, imposta le directory della cache e dei file temporanei in una posizione con spazio su disco sufficiente. Ad esempio, imposta sim_cache su una posizione 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 è intenzionalmente 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 qt6-qttranslations tbb


Prerequisiti software e installazione di Geant4 per la build di GEMC




Comandi di installazione in una riga per i pacchetti di base e le dipendenze su macOS e alcune diffuse distribuzioni Linux:


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 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. Per i Mac con Apple Silicon aggiungi l’opzione --platform linux/amd64 al comando docker run se vuoi usare le ↩