{"id":34520115,"url":"https://github.com/gemc/clas12tags","last_synced_at":"2026-06-06T06:05:03.721Z","repository":{"id":98894380,"uuid":"601677160","full_name":"gemc/clas12Tags","owner":"gemc","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-26T15:46:03.000Z","size":82486,"stargazers_count":2,"open_issues_count":9,"forks_count":24,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-26T16:31:45.424Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gemc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-14T15:26:55.000Z","updated_at":"2026-05-26T15:47:40.000Z","dependencies_parsed_at":"2025-07-07T15:34:36.196Z","dependency_job_id":"33eced15-38bc-410f-936e-15eda860ff8f","html_url":"https://github.com/gemc/clas12Tags","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/gemc/clas12Tags","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemc%2Fclas12Tags","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemc%2Fclas12Tags/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemc%2Fclas12Tags/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemc%2Fclas12Tags/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gemc","download_url":"https://codeload.github.com/gemc/clas12Tags/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemc%2Fclas12Tags/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33810343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T04:44:35.143Z","updated_at":"2026-06-02T07:00:46.884Z","avatar_url":"https://github.com/gemc.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The clas12Tags repository\n\n\n## QuickStart\n\nCreate the CLAS12 geometry database for the a detector (here we use CND)\n\n```bash\ngit clone https://github.com/gemc/clas12Tags\ncd clas12Tags\n./create_geometry.sh cnd     # build \u0026 install the CND detector databases\n```\n\nSetup the environment at Jefferson Lab, load a tagged version of gemc:\n\n```bash\nmodule use /scigroup/cvmfs/geant4/modules\nmodule load gemc/5.14\n```\n\nAlternatively, use the [clas12 environment](https://clasweb.jlab.org/wiki/index.php/CLAS12_Software_Environment_@_JLab)\nfor the full CLAS12 software stack, which includes the latest tagged gemc version.\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [General Information](#general-information)\n- [How to create the CLAS12 detector geometry database](#how-to-create-the-clas12-detector-geometry-database)\n\t- [Pre-requisites](#pre-requisites)\n\t- [Procedure](#procedure)\n\t\t- [Step 1: Clone the repository](#step-1-clone-the-repository)\n\t\t- [Step 2: Install coatjava](#step-2-install-coatjava)\n\t\t- [Step 3: Build the geometry database](#step-3-build-the-geometry-database)\n\t- [1. Create and Install the geometry database into the experiments directory](#1-create-and-install-the-geometry-database-into-the-experiments-directory)\n\t- [2. Debug / test a detector geometry in the geometry_source directory](#2-debug--test-a-detector-geometry-in-the-geometry_source-directory)\n- [How compile the source code at JLab](#how-compile-the-source-code-at-jlab)\n- [Release workflow](#release-workflow)\n\t- [Pull requests](#pull-requests)\n\t- [Run at JLab:](#run-at-jlab)\n- [Docker Images](#docker-images)\n- [Portal to Off-site farms CLAS12 Simulations](#portal-to-off-site-farms-clas12-simulations)\n- [Profiling](#profiling)\n\t- [Time per track](#time-per-track)\n- [Utilities](#utilities)\n\t- [Changing a material](#changing-a-material)\n\t- [Removing a detector or a volume](#removing-a-detector-or-a-volume)\n- [Citations](#citations)\n- [Maurizio Ungaro](#maurizio-ungaro)\n\n\u003cbr/\u003e\n\n## Introduction\n\nThe clas12Tags repository collects the databases and source code for the Geant4 simulation of the CLAS12 experiments\nat Jefferson Lab, providing:\n\n- Tagged version of the geometry database, in the form of ASCII and SQLite files.\n- The CLAS12 geometry source code used to create the geometry databases.\n- Detectors steering cards (GCARDS) for debugging and testing.\n- The GEMC C++ source code and perl API.\n\nThe `experiments` directory contains the **development version of the geometry database\nof the CLAS12 detectors**, built using the **latest tagged version of coatjava**.\n\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"clas12.png?raw=true\" alt=\"CLAS12 detector rendering\" width=\"600\"\u003e\n  \u003cbr\u003e\n  \u003cem\u003eFigure\u0026nbsp;1: The CLAS12 detector simulation. The electron beam travels left\u0026nbsp;→\u0026nbsp;right.\u003c/em\u003e\n\u003c/p\u003e\n\n## General Information:\n\n- [GEMC Documentation Page](https://gemc.jlab.org/gemc/html/index.html)\n- [CLAS12 Discourse Forum: Simulation](https://clas12.discourse.group/c/simulation/9)\n- [Clas12-config repository with the various experiments steering cards](https://github.com/JeffersonLab/clas12-config)\n- [CLAS12 Software Center Wiki](https://clasweb.jlab.org/wiki/index.php/CLAS12_Software_Center#tab=Communications)\n- [CCDB Viewer](https://clasweb.jlab.org/cgi-bin/ccdb/objects)\n\n\u003cbr/\u003e\n\n# How to create the CLAS12 geometry databases\n\n## Pre-requisites\n\nYou will need:\n\n- `maven`, `java (openjdk \u003e= 17)` and `groovy` to install and run the coatjava geometry service.\n- gemc `dev` environment.\n\nThe above requirements are met at JLab by loading the usual **clas12 module**,\nthen switching to gemc/dev:\n\n```bash\nmodule use /scigroup/cvmfs/hallb/clas12/sw/modulefiles\nmodule load clas12\nmodule switch gemc/dev\n```\n\n\u003e [!Caution]\n\u003e This will set the environment variables `GEMC` (used by the perl API; `GEMC`/bin added to your path) and\n\u003e `GEMC_DATA_DIR` (used by gemc to find the databases) to the /scigroup location.\n\u003e Notice:\n\u003e 1) If you are testing perl API changes, point **GEMC** to your cloned clas12Tags directory.\n\u003e 2) If you are testing geometry changes, point **GEMC_DATA_DIR** the cloned clas12Tags directory.\n\u003e 3) If you are testing changes within the geometry_source directory, you do not need to set any  \n\u003e    additional variables, as the detectors gcards load the local geometry database.\n\u003e 4) If you're testing changes in gemc code, make sure to use the `gemc` executable\n\u003e     in your cloned repository (source/gemc), or the one from the environment will be used instead.\n\n## Procedure:\n\nClone the clas12Tags repository:\n\n```bash\ngit clone https://github.com/gemc/clas12Tags\ncd clas12Tags\n```\n\nAt this point you can:\n\n1. create and install the geometry databases into the `experiments` directory\n2. debug / test a detector database inside the `geometry_source`\n   directory.\n\n\u003cbr/\u003e\n\n## 1. Create and Install the geometry databases into the `experiments` directory:\n\nThe script `create_geometry.sh` will create a single detector or all geometry databases:\n\n```\nUsage: create_geometry.sh [coatjava release options] [detector]\n\nCoatjava options (optional – at most one of -d|-l|-t|-g):\n  -l               use latest tag (default)\n  -t \u003ctag\u003e         use specific tag, like 12.0.4t\n  -g \u003cgithub_url\u003e  use custom github URL\n  -h               show this help\n\nIf a detector is given (from the list below), only that detector will be built; \notherwise all will be processed.\n\n  alert band beamline bst cnd ctof dc ddvcs ec fluxDets ft ftof \n  ftofShield htcc ltcc magnets micromegas pcal rich rtpc targets \n  uRwell upstream\n```\n\nThe script will install (if not present) the desired tagged coatjava in the directory\n`geometry_source` and run the geometry service for the requested detector(s).\n\n\u003cbr/\u003e\n\n\u003e [!Warning]\n\u003e By default, the latest coatjava tag is used. This is also the suggested option.\n\u003e Other tags can be used but they are not guaranteed to work.\n\n\u003cbr/\u003e\n\nExamples:\n\n- `./create_geometry.sh cnd`:\n\t- install if not present the latest coatjava tag,\n\t- create, and install in the `experiments` dir, the CND geometry ASCII database\n\t- create or update the SQLite database\n\n\n- `./create_geometry.sh`:\n\t- install if not present the latest coatjava tag\n\t- create, and install in the `experiments` dir, all the CLAS12 detectors geometry ASCII database\n\t- create or update the SQLite database\n\n\n- `./create_geometry.sh -t 12.0.4t bst`:\n\t- install the coatjava tag 12.0.4t\n\t- create, and install in the `experiments` dir, the BST geometry ASCII database\n\t- create or update the SQLite database\n\n\u003cbr/\u003e\n\n## 2. Debug / test a detector geometry in the `geometry_source` directory:\n\nIf you didn't run `create_geometry.sh`, install coatjava first, and create the sqlite geometry database:\n\n```bash\ncd geometry_source \n./install_coatjava.sh -l\n$GEMC/api/perl/sqlite.py -n ../clas12.sqlite\n```\n\nChange directory to detector of interest inside `geometry_source` and run\nthe geometry script to create the ASCII and SQLite databases: For example, for ftof:\n\n```bash\ncd geometry_source/ftof\n./ftof.pl config.dat\n```\n\nYou will see in the local directory the ASCII databases (geometry and materials txt files),\nand the SQLite database `clas12.sqlite` will be updated with the new detector.\n\n\u003cbr/\u003e\n\n\u003e [!NOTE]\n\u003e Each detector subdir has two sets of gcards:\n\u003e - `\u003cdetector\u003e_text_\u003cvariation\u003e.gcard`: for debugging the detector geometry\n\u003e   or a specific variation using the ASCII database.\n\u003e - `\u003cdectector\u003e_sqlite.gcard`: for running the detector geometry for a\n\u003e   specific run number using the SQLite database `clas12.sqlite`\n\u003e   in the `geometry_source` directory.\n\u003e - These gcards contain their detector's geometry but not\n\u003e   other CLAS12 components and will only load the detector geometry database in\n\u003e   the local directory.\n\n\n\u003cbr/\u003e\n\n# How to compile the source code at JLab\n\nLoad the **gemc/dev**,  **ccdb** and **hipo** modules as described above [^1].\n\nThen, change directory to the `source` directory and run:\n\n```bash\ncd source\nscons -jN OPT=1\n```\n\nwhere N is the number of cores available. At JLab, N=40 is a good choice.\n\n[^1]: for a standalone installation, follow the [ceInstall instructions](https://github.com/JeffersonLab/ceInstall).\n\n\n\u003cbr/\u003e\n\n# Release workflow\n\nMerging changes in the repository will trigger various CI validation workflows and the\n**creation of artifacts** containing the new executable and the\ngeometry databases.\n\nThese are installed at JLAB in /scigroup/cvmfs using a **cronjob that runs every couple of hours**.\n\nAs a result these JLAB installations are up-to-date with this timelines:\n\n- `/scigroup/cvmfs` (used on ifarms) : 2-8 hours after the commit, passing through the CI validation and\n  merge queue when necessary.\n- `/cvmfs/oasis.opensciencegrid.org` (used on OSG): an additional 4-8 hours after the JLAB\n  installation once the CVMFS sync runs.\n\nThe GitHub `dev` release is also created nightly by the CI.\n\n### Pull requests\n\nThe pull requests will be reviewed and queue for auto-merging into the\nmain branch pending passing the CI:\n\n- compilation for fedora36, almalinux94 and ubuntu24\n- coatjava validation with 500 events\n- run gemc on 1000 events using all gcards in clas12-config/gemc/dev development branch\n\n### Run at JLab:\n\nThe available modules can be listed using `module avail gemc`.\n\nTo run GEMC you can select one of the gcards in the clas12-config\ninstalled on cvmfs. For example:\n\n```bash\ngemc /scigroup/cvmfs/hallb/clas12/sw/noarch/clas12-config/dev/gemc/dev/rga_fall2018.gcard  -N=nevents -USE_GUI=0 \n```\n\n\u003e [!NOTE]\n\u003e - Make sure that the clas12-config version is production for a tagged release,\n\t\u003e or dev for the latest development version.\n\u003e - For **gemc/dev**, you will need to use the subdir `clas12-config/dev/gemc/dev`\n\n\n\u003cbr/\u003e\n\n## Docker images\n\nDocker images for Almalinux and Fedora  based OS systems\nare available on [DockerHub](https://hub.docker.com/repository/docker/jeffersonlab/gemc/general).\n\n- dev-fedora36\n- dev-almalinux94\n\nTo run the docker image (for example dev-fedora):\n\n```shell\ndocker run -it --rm jeffersonlab/gemc:dev-almalinux94 bash\n```\n\nOn MacOS the additional option `--platform linux/amd64` is needed:\n\n```shell\ndocker run -it --rm --platform linux/amd64 jeffersonlab/gemc:dev-almalinux94 bash\n```\n\nFor i/o to and from the image, you can include a mounting point by adding the `-v` option to the above command\n\n```shell\n-v ~/mywork:/usr/local/mywork \n```\n\n\u003cbr/\u003e\n\n# Portal to off-site farms CLAS12 Simulations\n\nCLAS12 GEMC simulations can be run on the Open Science Grid (OSG) using the\n\u003ca href=\"https://gemc.jlab.org/web_interface/index.php\"\u003e CLAS12 Simulation Submission Portal\u003c/a\u003e.\n\n\n\u003cbr/\u003e\n\n# Profiling\n\n## Time per track\n\nThe profile table below is obtained by a [metrics action](https://github.com/gemc/clas12Tags/actions/workflows/ntracs_metrics.yml)\nthat runs gemc nightly with the RGA Spring 2018 configuration, with a mix of 1, 2, 3, 5, 10, 15, 20 tracks,\nand by using clasdis.\n\nThe events come from a picking single tracks from a the following clas12 mcgen generators: clasdis, dvcsgen, las12-elspectro, gibuu, genKandOnePione, onepigen, twopeg.\n\nThe clasdis files are:\n\n- clasdis_all : generated with no options\n- clasdis_acc: generated with --t 15 35 option (electron theta between 15 and 35)\n\n![Track Profiling](ci/tracks_profile.png?raw=true \"Time per track for various configurations\")\n\n\n\n\u003cbr/\u003e\n\n# Utilities\n\n### Changing a material\n\nThe option `SWITCH_MATERIALTO` can be used to change a material of a volume\nFor example, to change the `G4_lH2` to vacuum:\n\n```\n\u003coption name=\"SWITCH_MATERIALTO\" value=\"G4_lH2, G4_Galactic\"/\u003e\n```\n\nThe option `CHANGEVOLUMEMATERIALTO` can be used to change the material of a volume.\nFor example, to change the target cell `lh2` material from LH2 to a vacuum:\n\n```\n\u003coption name=\"CHANGEVOLUMEMATERIALTO\" value=\"lh2, G4_Galactic\"/\u003e\n```\n\n### Removing a detector or a volume\n\nYou can remove/comment out the ```\u003cdetector\u003e``` tag in the gcard to remove a whole system.\nTo remove individual elements, use the existance tag in the gcard. For example, to remove the forward micromegas:\n\n```\n\u003cdetector name=\"FMT\"\u003e\n    \u003cexistence exist=\"no\" /\u003e\n\u003c/detector\u003e\n```\n\n\u003cbr/\u003e\n\n## Citations\n\nPlease make sure to cite the following paper if you use GEMC:\n\n- [Nucl. Instrum. Meth. A, Volume 959, 163422 (2020)](https://inspirehep.net/literature/1780020)\n- [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)\n\n\u003cbr/\u003e\n\n## Author\n\nMaurizio Ungaro\n\n\u003ca href=\"https://scholar.google.com/citations?user=zkWYILYAAAAJ\u0026amp;hl=en\" target=\"_blank\"\u003e\u003cimg class=\"zoomIcon\" src=\"https://maureeungaro.github.io/home/assets/images/home/gscholar.png\"\u003e \u003c/a\u003e\n\u003ca href=\"https://github.com/maureeungaro\" target=\"_blank\"\u003e\u003ca href=\"mailto:ungaro@jlab.org\"\u003e\u003cimg class=\"zoomIcon\" src=\"https://maureeungaro.github.io/home/assets/images/home/github.png\"\u003e \u003c/a\u003e\n\u003ca href=\"https://inspirehep.net/authors/1322331\" target=\"_blank\"\u003e\u003cimg class=\"zoomIcon\" src=\"https://maureeungaro.github.io/home/assets/images/home/inspire.png\"\u003e \u003c/a\u003e\n\u003ca href=\"mailto:ungaro@jlab.org\"\u003e\u003cimg class=\"zoomIcon\" src=\"https://maureeungaro.github.io/home/assets/images/home/email.png\"\u003e \u003c/a\u003e\n\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n\u003chr\u003e\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n# CI\n\n### Pull requests\n\n- [![Almalinux Build](https://github.com/gemc/clas12Tags/actions/workflows/build_gemc_almalinux.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/build_gemc_almalinux.yml) [![Fedora Build](https://github.com/gemc/clas12Tags/actions/workflows/build_gemc_fedora.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/build_gemc_fedora.yml) [![Ubuntu Build](https://github.com/gemc/clas12Tags/actions/workflows/build_gemc_ubuntu.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/build_gemc_ubuntu.yml)\n- [![Clas12-Config GCards Tests](https://github.com/gemc/clas12Tags/actions/workflows/clas12_config_gcards_test.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/clas12_config_gcards_test.yml)\n- [![CodeQL Advanced](https://github.com/gemc/clas12Tags/actions/workflows/codeql.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/codeql.yml)\n- [![Ntracks Metrics](https://github.com/gemc/clas12Tags/actions/workflows/ntracs_metrics.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/ntracs_metrics.yml)\n- [![Local Gcards Tests](https://github.com/gemc/clas12Tags/actions/workflows/local_gcards.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/local_gcards.yml)\n- [![Tracks Validation](https://github.com/gemc/clas12Tags/actions/workflows/tracks_validation.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/tracks_validation.yml)\n\n### Nightly\n\n- [![Nightly Dev Release](https://github.com/gemc/clas12Tags/actions/workflows/dev_release.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/dev_release.yml)\n- [![Valgrind-Profile](https://github.com/gemc/clas12Tags/actions/workflows/valgrind_profile.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/valgrind_profile.yml)\n- [![Ascii vs Sqlite](https://github.com/gemc/clas12Tags/actions/workflows/ascii_sqlite_comparison.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/ascii_sqlite_comparison.yml)\n- [![Clas12-config Dev Main Comparison](https://github.com/gemc/clas12Tags/actions/workflows/clas12_config_dev_main_comparison.yml/badge.svg)](https://github.com/gemc/clas12Tags/actions/workflows/clas12_config_dev_main_comparison.yml)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgemc%2Fclas12tags","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgemc%2Fclas12tags","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgemc%2Fclas12tags/lists"}