Skip to content

0.1

Latest
Latest

Choose a tag to compare

View all tags
@maureeungaro maureeungaro released this 17 Jun 18:07
· 9 commits to main since this release
0.1
ab95162

CLAS12 GEMC Systems 0.1

Initial development release for the GEMC3 CLAS12 systems repository. This repository contains the geometry
builders, digitization plugins, steering cards, and validation tools for CLAS12 detector systems.

This version includes:

  • First GEMC3 CLAS12 detector port: DC geometry in geometry_src/dc.
  • A DC digitization plugin with configurable readout timing and CLAS12 translation-table support.
  • CLAS12 HIPO output for detector ADC, TDC, and waveform banks.
  • hipo-histos summaries and two-file comparisons for DC validation.
  • Top-level Meson integration for CLAS12 systems, plugins, tests, and installation metadata.
  • Local coatjava setup support for geometry services used by CLAS12 systems.

Release notes

  • Established the CLAS12 systems repository as the GEMC3 companion for CLAS12 detector geometry,
    digitization plugins, and validation tools.
  • Added the first detector system, dc, including GEMC3 geometry generation from the CLAS12 coatjava geometry
    service.
  • Added a DC digitization plugin that registers its own GEMC options and publishes detector-specific readout
    variables.
  • Added CLAS12 HIPO streamer support so detector digitization output can be written to schema-aware ADC, TDC,
    and waveform banks.
  • Added DC HIPO histogramming and comparison tools for geometry and digitization validation.
  • Added repository-level build, CI, documentation, and coatjava setup needed for future CLAS12 detector systems.

Documentation

  • Expanded the README with repository scope, layout, build/test workflow, coatjava notes, plugin conventions,
    and validation guidance.
  • Added GEMC home-site documentation for custom GDynamicDigitization plugins.
  • Added documentation links and workflow badges for the new CLAS12 systems workflows.

Tests

  • Added per-system geometry tests for detector scripts under geometry_src.
  • Added semantic ASCII geometry comparison support for CLAS12Tags validation.
  • Added CI coverage for deploy/test, sanitizers, CodeQL, Doxygen, development releases, and binary tarballs.

Addressed issues


Supported platforms

Both x86_64 and ARM64 platforms are supported.

  • macOS: 26
  • Ubuntu: 24.04, 26.04
  • AlmaLinux: 10
  • Fedora: 44
  • Debian: 13
  • Arch Linux: latest

Dependencies

  • Geant4: 11.4.1 or higher
  • CLHEP: 2.4.6.0 or higher
  • Xerces-C: 3.2 or higher
  • GEMC: 0.3

Compatibility notes

  • CLAS12 detector geometry ported from GEMC2 should use g4placement_type = "passive" in GVolume.
  • Ordered rotations from CLAS12Tags should remain ordered in the database, for example ordered: yxz, ....
  • The obsolete DC original variation is intentionally not supported by the GEMC3 DC port.
  • The default DC geometry run is 11.

Detailed list of changes and fixes

  • Added the executable geometry_src/dc/dc.py entry point and detector-local geometry.py, materials.py,
    variations.py, and dc.yaml files.
  • Added a Python coatjava bridge in geometry_src/dc/coatjava.py that runs the local helper in
    geometry_src/coatjava_factories/CoatjavaFactory.java, parses the generated DC volume table, and writes GEMC3
    geometry through pygemc.autogeometry.
  • Added local DC run and variation mapping in geometry_src/dc/variations.py.
  • Preserved CLAS12Tags ordered rotations in the generated database instead of flattening them to plain x/y/z
    rotations.
  • Marked DC volumes with g4placement_type = "passive" so Geant4 uses the GEMC2/clas12Tags placement convention
    for ported CLAS12 detector geometry.
  • Added the top-level Meson build used to register CLAS12 detector systems.
  • Added the clas12_systems registry pattern.
  • Added the shared plugin registry model for future detector .gplugin shared libraries.
  • Installed CLAS12 plugins expose their directory through a generated clas12-systems.pc pkg-config file, so
    callers can locate plugins with pkg-config --variable=plugindir clas12-systems.
  • Added the DC digitization plugin under geometry_src/dc/plugin/, including readout-spec definitions,
    calibration-constant loading, translation-table loading, touchable processing, and hit digitization.
  • Added definePluginOptions() for DC plugin options. GEMC probes this symbol before option parsing, so
    DC-specific options appear in gemc dc.yaml -h, are saved to configuration snapshots, and can be set from
    YAML or the command line.
  • Added the configurable dc_timeWindow option, replacing the previously hardcoded electronics integration
    window. Users can set it in YAML or with -dc_timeWindow=<ns>.
  • Added "dc" as an independent verbosity key, so DC plugin logging can be controlled separately from global
    gdigitization logging.
  • Added CLAS12 digitized-data publishing through the HIPO streamer plugin. ADC, TDC, and waveform banks are
    enabled from the digitization output variables present in each detector hit.
  • Added schema-aware HIPO column writing for byte, short, int, long, float, and double columns using the target
    HIPO schema type instead of assuming one fixed C++ type per variable.
  • Treated touchable identities as defaults only. Detector digitization plugins may override bank columns with
    explicitly published output variables when a schema column has detector-specific meaning, such as DC global
    layer 1..36 instead of the touchable-local layer.
  • Supported both prefixed digitization variables (ADC_*, TDC_*, WF_*) and direct schema-column variables.
  • Added hipo-histos to read HIPO files, fill ROOT histograms, and write PNG summary plots. The first supported
    subsystem is dc, using MC::True and DC::tdc.
  • Added DC summary plots for occupancy, r-vs-z, z-vertex, region and sector TDC distributions, and layer-wire
    occupancy.
  • Added two-file DC comparison mode with overlay PNGs, event-count normalization for unequal input sizes,
    optional ROOT interactive mode, and CI-friendly --fail-on-diff thresholds.
  • Added diagnostic comparison output with pass/fail status, chi2/ndf, relative integral difference, maximum bin
    difference, occupied-bin counts, and median entries per occupied bin.
  • Propagated ROOT bin errors into comparison plots and diagnostics, including Poisson fallbacks for histograms
    without explicit errors.
  • Computed DC z-vertex and occupancy-summary uncertainties from event-to-event fluctuations, which is better
    matched to correlated DC hits from the same simulated event.
  • Added local coatjava installation support through geometry_src/install_coatjava.sh and Meson configure-time
    setup when geometry_src/coatjava is missing.
  • Added CI helpers to install Java, Maven, git-lfs, and jq before coatjava setup.
  • Added per-system geometry tests that run geometry_src/<system>/<system>.py from the detector directory.
  • Updated scripts/compare_ascii_geometry.py to compare semantic geometry records by volume name and report
    field-level differences with --diff.
  • The DC default geometry is expected to token-match
    ../clas12Tags/geometry_source/dc/dc__geometry_default.txt for shared GEMC geometry fields.
  • Added README workflow badges for Test, Deploy, Sanitize, CodeQL, Doxygen, Binary Tarballs, and Nightly Dev
    Release.
  • Added README guidance for comparing generated GEMC3 ASCII geometry against the CLAS12Tags reference files.
  • Added GEMC home-site documentation for the full GDynamicDigitization plugin contract, including class
    skeleton, factory entry point, override reference table, defineReadoutSpecsImpl, digitizeHitImpl,
    plugin-specific options, verbosity setup, plugin search path priority, and the Meson build pattern.
  • Updated the GEMC home-site sensitivity index to link to the custom plugin documentation.
Assets 2
Loading