https://github.com/gemc/clas12tags
https://github.com/gemc/clas12tags
Last synced: 9 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/gemc/clas12tags
- Owner: gemc
- Created: 2023-02-14T15:26:55.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-05-26T15:46:03.000Z (20 days ago)
- Last Synced: 2026-05-26T16:31:45.424Z (20 days ago)
- Language: C
- Size: 78.7 MB
- Stars: 2
- Watchers: 3
- Forks: 24
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# The clas12Tags repository
## QuickStart
Create the CLAS12 geometry database for the a detector (here we use CND)
```bash
git clone https://github.com/gemc/clas12Tags
cd clas12Tags
./create_geometry.sh cnd # build & install the CND detector databases
```
Setup the environment at Jefferson Lab, load a tagged version of gemc:
```bash
module use /scigroup/cvmfs/geant4/modules
module load gemc/5.14
```
Alternatively, use the [clas12 environment](https://clasweb.jlab.org/wiki/index.php/CLAS12_Software_Environment_@_JLab)
for the full CLAS12 software stack, which includes the latest tagged gemc version.
## Table of Contents
- [Introduction](#introduction)
- [General Information](#general-information)
- [How to create the CLAS12 detector geometry database](#how-to-create-the-clas12-detector-geometry-database)
- [Pre-requisites](#pre-requisites)
- [Procedure](#procedure)
- [Step 1: Clone the repository](#step-1-clone-the-repository)
- [Step 2: Install coatjava](#step-2-install-coatjava)
- [Step 3: Build the geometry database](#step-3-build-the-geometry-database)
- [1. Create and Install the geometry database into the experiments directory](#1-create-and-install-the-geometry-database-into-the-experiments-directory)
- [2. Debug / test a detector geometry in the geometry_source directory](#2-debug--test-a-detector-geometry-in-the-geometry_source-directory)
- [How compile the source code at JLab](#how-compile-the-source-code-at-jlab)
- [Release workflow](#release-workflow)
- [Pull requests](#pull-requests)
- [Run at JLab:](#run-at-jlab)
- [Docker Images](#docker-images)
- [Portal to Off-site farms CLAS12 Simulations](#portal-to-off-site-farms-clas12-simulations)
- [Profiling](#profiling)
- [Time per track](#time-per-track)
- [Utilities](#utilities)
- [Changing a material](#changing-a-material)
- [Removing a detector or a volume](#removing-a-detector-or-a-volume)
- [Citations](#citations)
- [Maurizio Ungaro](#maurizio-ungaro)
## Introduction
The clas12Tags repository collects the databases and source code for the Geant4 simulation of the CLAS12 experiments
at Jefferson Lab, providing:
- Tagged version of the geometry database, in the form of ASCII and SQLite files.
- The CLAS12 geometry source code used to create the geometry databases.
- Detectors steering cards (GCARDS) for debugging and testing.
- The GEMC C++ source code and perl API.
The `experiments` directory contains the **development version of the geometry database
of the CLAS12 detectors**, built using the **latest tagged version of coatjava**.
Figure 1: The CLAS12 detector simulation. The electron beam travels left → right.
## General Information:
- [GEMC Documentation Page](https://gemc.jlab.org/gemc/html/index.html)
- [CLAS12 Discourse Forum: Simulation](https://clas12.discourse.group/c/simulation/9)
- [Clas12-config repository with the various experiments steering cards](https://github.com/JeffersonLab/clas12-config)
- [CLAS12 Software Center Wiki](https://clasweb.jlab.org/wiki/index.php/CLAS12_Software_Center#tab=Communications)
- [CCDB Viewer](https://clasweb.jlab.org/cgi-bin/ccdb/objects)
# How to create the CLAS12 geometry databases
## Pre-requisites
You will need:
- `maven`, `java (openjdk >= 17)` and `groovy` to install and run the coatjava geometry service.
- gemc `dev` environment.
The above requirements are met at JLab by loading the usual **clas12 module**,
then switching to gemc/dev:
```bash
module use /scigroup/cvmfs/hallb/clas12/sw/modulefiles
module load clas12
module switch gemc/dev
```
> [!Caution]
> This will set the environment variables `GEMC` (used by the perl API; `GEMC`/bin added to your path) and
> `GEMC_DATA_DIR` (used by gemc to find the databases) to the /scigroup location.
> Notice:
> 1) If you are testing perl API changes, point **GEMC** to your cloned clas12Tags directory.
> 2) If you are testing geometry changes, point **GEMC_DATA_DIR** the cloned clas12Tags directory.
> 3) If you are testing changes within the geometry_source directory, you do not need to set any
> additional variables, as the detectors gcards load the local geometry database.
> 4) If you're testing changes in gemc code, make sure to use the `gemc` executable
> in your cloned repository (source/gemc), or the one from the environment will be used instead.
## Procedure:
Clone the clas12Tags repository:
```bash
git clone https://github.com/gemc/clas12Tags
cd clas12Tags
```
At this point you can:
1. create and install the geometry databases into the `experiments` directory
2. debug / test a detector database inside the `geometry_source`
directory.
## 1. Create and Install the geometry databases into the `experiments` directory:
The script `create_geometry.sh` will create a single detector or all geometry databases:
```
Usage: create_geometry.sh [coatjava release options] [detector]
Coatjava options (optional – at most one of -d|-l|-t|-g):
-l use latest tag (default)
-t use specific tag, like 12.0.4t
-g use custom github URL
-h show this help
If a detector is given (from the list below), only that detector will be built;
otherwise all will be processed.
alert band beamline bst cnd ctof dc ddvcs ec fluxDets ft ftof
ftofShield htcc ltcc magnets micromegas pcal rich rtpc targets
uRwell upstream
```
The script will install (if not present) the desired tagged coatjava in the directory
`geometry_source` and run the geometry service for the requested detector(s).
> [!Warning]
> By default, the latest coatjava tag is used. This is also the suggested option.
> Other tags can be used but they are not guaranteed to work.
Examples:
- `./create_geometry.sh cnd`:
- install if not present the latest coatjava tag,
- create, and install in the `experiments` dir, the CND geometry ASCII database
- create or update the SQLite database
- `./create_geometry.sh`:
- install if not present the latest coatjava tag
- create, and install in the `experiments` dir, all the CLAS12 detectors geometry ASCII database
- create or update the SQLite database
- `./create_geometry.sh -t 12.0.4t bst`:
- install the coatjava tag 12.0.4t
- create, and install in the `experiments` dir, the BST geometry ASCII database
- create or update the SQLite database
## 2. Debug / test a detector geometry in the `geometry_source` directory:
If you didn't run `create_geometry.sh`, install coatjava first, and create the sqlite geometry database:
```bash
cd geometry_source
./install_coatjava.sh -l
$GEMC/api/perl/sqlite.py -n ../clas12.sqlite
```
Change directory to detector of interest inside `geometry_source` and run
the geometry script to create the ASCII and SQLite databases: For example, for ftof:
```bash
cd geometry_source/ftof
./ftof.pl config.dat
```
You will see in the local directory the ASCII databases (geometry and materials txt files),
and the SQLite database `clas12.sqlite` will be updated with the new detector.
> [!NOTE]
> Each detector subdir has two sets of gcards:
> - `_text_.gcard`: for debugging the detector geometry
> or a specific variation using the ASCII database.
> - `_sqlite.gcard`: for running the detector geometry for a
> specific run number using the SQLite database `clas12.sqlite`
> in the `geometry_source` directory.
> - These gcards contain their detector's geometry but not
> other CLAS12 components and will only load the detector geometry database in
> the local directory.
# How to compile the source code at JLab
Load the **gemc/dev**, **ccdb** and **hipo** modules as described above [^1].
Then, change directory to the `source` directory and run:
```bash
cd source
scons -jN OPT=1
```
where N is the number of cores available. At JLab, N=40 is a good choice.
[^1]: for a standalone installation, follow the [ceInstall instructions](https://github.com/JeffersonLab/ceInstall).
# Release workflow
Merging changes in the repository will trigger various CI validation workflows and the
**creation of artifacts** containing the new executable and the
geometry databases.
These are installed at JLAB in /scigroup/cvmfs using a **cronjob that runs every couple of hours**.
As a result these JLAB installations are up-to-date with this timelines:
- `/scigroup/cvmfs` (used on ifarms) : 2-8 hours after the commit, passing through the CI validation and
merge queue when necessary.
- `/cvmfs/oasis.opensciencegrid.org` (used on OSG): an additional 4-8 hours after the JLAB
installation once the CVMFS sync runs.
The GitHub `dev` release is also created nightly by the CI.
### Pull requests
The pull requests will be reviewed and queue for auto-merging into the
main branch pending passing the CI:
- compilation for fedora36, almalinux94 and ubuntu24
- coatjava validation with 500 events
- run gemc on 1000 events using all gcards in clas12-config/gemc/dev development branch
### Run at JLab:
The available modules can be listed using `module avail gemc`.
To run GEMC you can select one of the gcards in the clas12-config
installed on cvmfs. For example:
```bash
gemc /scigroup/cvmfs/hallb/clas12/sw/noarch/clas12-config/dev/gemc/dev/rga_fall2018.gcard -N=nevents -USE_GUI=0
```
> [!NOTE]
> - Make sure that the clas12-config version is production for a tagged release,
> or dev for the latest development version.
> - For **gemc/dev**, you will need to use the subdir `clas12-config/dev/gemc/dev`
## Docker images
Docker images for Almalinux and Fedora based OS systems
are available on [DockerHub](https://hub.docker.com/repository/docker/jeffersonlab/gemc/general).
- dev-fedora36
- dev-almalinux94
To run the docker image (for example dev-fedora):
```shell
docker run -it --rm jeffersonlab/gemc:dev-almalinux94 bash
```
On MacOS the additional option `--platform linux/amd64` is needed:
```shell
docker run -it --rm --platform linux/amd64 jeffersonlab/gemc:dev-almalinux94 bash
```
For i/o to and from the image, you can include a mounting point by adding the `-v` option to the above command
```shell
-v ~/mywork:/usr/local/mywork
```
# Portal to off-site farms CLAS12 Simulations
CLAS12 GEMC simulations can be run on the Open Science Grid (OSG) using the
CLAS12 Simulation Submission Portal.
# Profiling
## Time per track
The profile table below is obtained by a [metrics action](https://github.com/gemc/clas12Tags/actions/workflows/ntracs_metrics.yml)
that runs gemc nightly with the RGA Spring 2018 configuration, with a mix of 1, 2, 3, 5, 10, 15, 20 tracks,
and by using clasdis.
The events come from a picking single tracks from a the following clas12 mcgen generators: clasdis, dvcsgen, las12-elspectro, gibuu, genKandOnePione, onepigen, twopeg.
The clasdis files are:
- clasdis_all : generated with no options
- clasdis_acc: generated with --t 15 35 option (electron theta between 15 and 35)
# Utilities
### Changing a material
The option `SWITCH_MATERIALTO` can be used to change a material of a volume
For example, to change the `G4_lH2` to vacuum:
```
```
The option `CHANGEVOLUMEMATERIALTO` can be used to change the material of a volume.
For example, to change the target cell `lh2` material from LH2 to a vacuum:
```
```
### Removing a detector or a volume
You can remove/comment out the `````` tag in the gcard to remove a whole system.
To remove individual elements, use the existance tag in the gcard. For example, to remove the forward micromegas:
```
```
## Citations
Please make sure to cite the following paper if you use GEMC:
- [Nucl. Instrum. Meth. A, Volume 959, 163422 (2020)](https://inspirehep.net/literature/1780020)
- [EPJ Web of Conf. Volume 295, 05505 (2024)](https://www.epj-conferences.org/articles/epjconf/abs/2024/05/epjconf_chep2024_05005/epjconf_chep2024_05005.html)
## Author
Maurizio Ungaro
# CI
### Pull requests
- [](https://github.com/gemc/clas12Tags/actions/workflows/build_gemc_almalinux.yml) [](https://github.com/gemc/clas12Tags/actions/workflows/build_gemc_fedora.yml) [](https://github.com/gemc/clas12Tags/actions/workflows/build_gemc_ubuntu.yml)
- [](https://github.com/gemc/clas12Tags/actions/workflows/clas12_config_gcards_test.yml)
- [](https://github.com/gemc/clas12Tags/actions/workflows/codeql.yml)
- [](https://github.com/gemc/clas12Tags/actions/workflows/ntracs_metrics.yml)
- [](https://github.com/gemc/clas12Tags/actions/workflows/local_gcards.yml)
- [](https://github.com/gemc/clas12Tags/actions/workflows/tracks_validation.yml)
### Nightly
- [](https://github.com/gemc/clas12Tags/actions/workflows/dev_release.yml)
- [](https://github.com/gemc/clas12Tags/actions/workflows/valgrind_profile.yml)
- [](https://github.com/gemc/clas12Tags/actions/workflows/ascii_sqlite_comparison.yml)
- [](https://github.com/gemc/clas12Tags/actions/workflows/clas12_config_dev_main_comparison.yml)
