The clas12Tags repository

Pull requests

• 
• 
• 
• 
• 
• 

Nightly

• 
• 
• 
• 

QuickStart

git clone https://github.com/gemc/clas12Tags
cd clas12Tags
./create_geometry.sh cnd     # build & install the CND detector databases

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 is the Geant4 simulation resource for the CLAS12 experiments at Jefferson Lab, providing:

• The CLAS12 geometry databases, in the form of ASCII and SQLite files.
• The CLAS12 geometry source code. It creates the geometry databases.
• Detectors steering cards (GCARDS) for debugging and testing.
• The GEMC c++ source code and perl API.

The experiments directory contains the latest 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 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. Be careful:

1. If you are testing specific perl API changes, point GEMC the cloned clas12Tags directory.
2. If you are testing geometry changes using the clas12-config gcards,
   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 installed in the GEMC/bin directory 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 the CND geometry ASCII database
  • create or update updates the SQLite database

• ./create_geometry.sh:

  • install if not present the latest coatjava tag
  • create all the CLAS12 detectors
  • create or update updates the SQLite database

• ./create_geometry.sh -t 12.0.4t bst:

  • install the coatjava tag 12.0.4t
  • create the BST geometry ASCII database
  • create or update updates the SQLite database

2. Debug / test a detector geometry in the geometry_source directory:

The script above run a script to install coatjava and creates the SQLite database. If you didn't run create_geometry.sh you need to do these things manually. For example, to install the latest coatjava and create the geometry database for the CND detector:

cd geometry_source 
./install_coatjava.sh -l
cd cnd
$GEMC/api/perl/sqlite.py -n ../../clas12.sqlite
./cnd.pl config.dat

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 for a specific variation. These uses the ASCII database.
• <dectector>_sqlite.gcard: for running the detector geometry for a specific run number. This uses 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 environment as described above ¹², then:

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

Use module switch to change to the desired version.

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 also need to use the subdir clas12-config/dev/gemc/dev You can used gemc -v to check the version of gemc.

Docker images

Docker images for Almalinux, Fedora and Ubuntu based OS systems are available on DockerHub.

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

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

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

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

docker run -it --rm --platform linux/amd64 jeffersonlab/gemc:dev-fedora36 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 GitHub 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)

Maurizio Ungaro

Footnotes

1. you will need to load the ccdb and hipo modules, included when with the clas12 module. ↩

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