The clas12Tags repository

QuickStart

Create the CLAS12 geometry database for the CND detector:

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 or the dev version of gemc:

module use /scigroup/cvmfs/geant4/modules
module load gemc/5.11
module load gemc/dev

Alternatively, use the clas12 environment for the full CLAS12 software stack, which includes the latest tagged gemc version.

Table of Contents

• Introduction
• General Information
• How to create the CLAS12 detector geometry database
  • Pre-requisites
  • Procedure
    • Step 1: Clone the repository
    • Step 2: Install coatjava
    • Step 3: Build the geometry database
  • 1. Create and Install the geometry database into the experiments directory
  • 2. Debug / test a detector geometry in the geometry_source directory
• How compile the source code at JLab
• Release workflow
  • Pull requests
  • Run at JLab:
• Docker Images
• Portal to Off-site farms CLAS12 Simulations
• Profiling
  • Time per track
• Utilities
  • Changing a material
  • Removing a detector or a volume
• Citations
• 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
• CLAS12 Discourse Forum: Simulation
• Clas12-config repository with the various experiments steering cards
• CLAS12 Software Center Wiki
• CCDB Viewer

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:

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 the cloned repository, or the one from the environment will be used instead.

Procedure:

Clone the clas12Tags repository:

git clone https://github.com/gemc/clas12Tags
cd clas12Tags

At this point you can either:

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 <tag>         use specific tag, like 12.0.4t
  -g <github_url>  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:

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:

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:

• <detector>_text_<variation>.gcard: for debugging the detector geometry or a specific variation using the ASCII database.
• <dectector>_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 ¹.

Then, change directory to the source directory and run:

cd source
scons -jN OPT=1

where N is the number of cores available. At JLab, N=40 is a good choice.

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:

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, Fedora and Ubuntu based OS systems are available on DockerHub.

• dev-ubuntu24
• dev-fedora36
• dev-fedora40
• dev-almalinux94

To run the docker image (for example dev-fedora):

docker run -it --rm jeffersonlab/gemc:dev-almalinux94 bash

On MacOS the additional option --platform linux/amd64 is needed:

docker run -it --rm --platform linux/amd64 jeffersonlab/gemc:dev-almalinux94 bash

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 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:

<option name="SWITCH_MATERIALTO" value="G4_lH2, G4_Galactic"/>

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:

<option name="CHANGEVOLUMEMATERIALTO" value="lh2, G4_Galactic"/>

Removing a detector or a volume

You can remove/comment out the <detector> 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:

<detector name="FMT">
    <existence exist="no" />
</detector>

Citations

• Nucl. Instrum. Meth. A, Volume 959, 163422 (2020)
• EPJ Web of Conf. Volume 295, 05505 (2024)

Author

Maurizio Ungaro

---

CI

Pull requests

• 
• 
• 
• 
• 
• 

Nightly

• 
• 
• 
• 

Footnotes

1. for a standalone installation, follow the ceInstall instructions. ↩