0.3

CLAS12 GEMC Systems 0.3

This version includes:

• Installation from scratch with no pre-existing GEMC: GEMC is compiled from the gemc subproject on a bare
  Geant4 environment, verified in CI on g4install images across every supported distro.
• The CLAS12 Forward Tagger geometry and digitization: FTCAL, FTHODO, and variation-dependent FTTRK.
• The CLAS12 HTCC geometry and digitization: native mirrors and PMTs, the CAD cones, and the nphe plugin.

Release notes

• Added independent installation-path options for CCDB, HIPO, and clas12-cmag to skip their subprojects.

• GEMC can now be built as a subproject, so CLAS12 systems install from scratch without a pre-existing GEMC:
  with no installed GEMC and no -Duse-gemc-location, the build compiles GEMC from the new gemc wrap and
  installs it into the same prefix. -Duse-gemc-location=<dir> reuses an existing GEMC install, and an
  installed GEMC on pkg-config/PATH is still preferred over building. Geant4 is never built and must already
  be available, or configuration fails.

• The field plugin now honors use-fields-location as its default map directory while preserving explicit
  field dir overrides and the relocatable installed-map default.

• Added FT-Cal streaming readout through GEMC's sro factory, with translation-table electronics routing
  and JLAB integral frames written by one thread per crate.

• Added the ft system with the PbWO4 calorimeter, scintillator hodoscope, Micromegas tracker, support
  structures, custom materials, and all eight run-group variations from clas12Tags.

• Added the htcc system, ported from clas12Tags: the native CO2 gas volume, entry/exit windows, 48
  elliptical mirrors (boolean cuts of a polycone barrel and an ellipsoid front surface), and 48 Winston-cone
  PMTs, across the default, rga_spring2018 and rga_fall2018 variations. The three beamline CAD cones
  (htccCone, htccMollerCone, htccMollerConeExt) are cured/decimated into watertight solids in a
  companion htcc_cad system. The htcc digitization plugin reproduces the clas12Tags nphe response:
  photocathode quantum efficiency on optical photons, ADC = gain * Gauss(nphe*mc_gain, nphe*mc_smear), and
  per-half/per-ring time offsets. Native HTCC ellipsoids require GEMC's new G4Ellipsoid native solid (see
  the src release notes).

• Added the ft_cal, ft_hodo, and ft_trk digitization plugins, including the FTCAL/FTHODO CCDB constants
  and translation tables and FTTRK multi-strip charge sharing.

• CLAS12 field maps now come from the magfield git-lfs subproject and are copied into <prefix>/fields at
  meson install (no download). -Duse-fields-location=<dir> reuses an existing maps directory instead.

• Bundled subprojects (ccdb, hipo-cpp, clas12-cmag) no longer install their libraries, headers, tools, or
  tests by default; enable -Dinclude-subproject-install=true / -Dinclude-subproject-tests=true to opt in.

Documentation

• Documented all dependency/map paths (including use-gemc-location and the GEMC subproject fallback),
  installation layouts, and the CCDB checkout refresh procedure.

• Documented FT-Cal SRO configuration, timing bounds, payload encoding, and current format limitations.

• Documented the git-lfs magfield field-map mechanism and the -Duse-fields-location option in the README.

Tests

• Added a GEMC construction smoke test for every detector, including native and CAD geometry and plugin
  loading, using the generated database and installed executable in the clas12 suite.

• Updated macOS tarball builds to compile GEMC from its subproject, requiring only the prebuilt Geant4
  archive, and report available release assets when the Geant4 download fails.

• Checked named DAQ header setup, metadata overrides, length overflow, and 64-bit word ordering.

• Added offline JLAB format fixtures and a full FT-Cal CCDB-to-crate test with one and four workers.

• Added FT to the Meson geometry suite and the automatic GEMC2 ASCII geometry/material comparison.

• Added a runnable FT steering card that loads all three digitizers from the sensitive geometry rows.

• Added HIPO ADC_ADC comparisons for LTCC and the FTCAL, FTHODO, and FTTRK banks.

• Added HTCC to the Meson geometry suite and the ASCII comparison, and generalized the semantic comparator to
  treat GEMC2 absolute-placement boolean spellings (Operation:@), sub-micron and unit-only numeric
  differences, and passive mirror surfaces as equal.

• Added the htcc hipo-histos subsystem (HTCC::adc/HTCC::tdc, detector 15) and its entry in the
  GEMC2-reference ADC/TDC comparison workflow.

• Serialized image deployments, preserved the running deployment when a newer one is scheduled, and ensured
  each eligible deployment checks out the commit that passed its triggering test.

• Standardized container workflows on Geant4-only ghcr.io/gemc/g4install images, building GEMC from source
  for deployment, sanitizers, comparisons, profiling, and smoke tests while preserving published image tags.

Addressed issues

• Issue #12: Add HTCC geometry and plugin
• Issue #15: Forward Tracker

Supported platforms

Dependencies

Compatibility notes

• FT-Cal SRO requires GEMC's current GSROImplementation API and an explicitly configured eventTimeWidth.

• Updated the CLAS12 plugins for GEMC 0.5's scoped electronic-address comparison modes and required scalar
  option accessors.

Detailed list of changes and fixes

• Expose the relocated Geant4, CLHEP, and Xerces libraries to macOS dyld so the installed GEMC can run
  during the full-path FT-Cal SRO test in tarball CI.

• Select the macOS Geant4 archive by configured Geant4 version and runner macOS/Clang version, allowing
  older builds to remain on the same release without failing the download step.

• Corrected a malformed pygemc wrap section header that prevented Meson configuration in CI.

• Resolve the Geant4 core dependency through the GEMC source subproject when a Geant4-only installation
  has no GEMC-generated pkg-config files yet.

• Let plugins resolve gdata symbols from GEMC like other framework symbols, removing the static-archive
  requirement that broke builds against profiling images.

• Unified the compiled external field-map default with GEMC2 through GEMC_DEFAULT_FIELD_DIR.

• Applied the CCDB system-SQLite wrap patch and enabled CCDB_USE_SYSTEM_SQLITE, removing the bundled
  SQLite targets and detecting stale unpatched subproject checkouts during configuration.

• Ported the required DAQ definitions into DataFrameHeader with centralized setup, serialization, and
  layout checks; removed obsolete source copies and documented their provenance and port decisions.
  FT-Hodo and FT-TRK remain without SRO, matching the supplied old code.

• Routed every detector geometry volume through pygemc's GVolume.publish_passive() API. FT now constructs
  and publishes each GVolume directly, and its primitives plus directly authored LTCC boxes, tubes, and traps
  use pygemc solid builders.

• The semantic ASCII comparator now canonicalizes non-zero numeric tokens and maps the GEMC2/GEMC3 polycone
  array orders, treating equivalent geometry values as equal while continuing to compare their units.

• Added an options-only ft.gplugin bootstrap registrar because the FT geometry selects three independent
  digitizers while a YAML gsystem.digitization override accepts one plugin name.

• Updated FTCAL translation-table keys to {ix, iy}, matching the sensitive geometry and direct worker lookup.
  FTCAL and FTHODO retain crate comparison mode; FTHODO retains order in its detector identity.

• Qualified the CLAS12 magnetic-field plugin's error code with its GEMC 0.5 gfields namespace.

• Split LTCC native and mesh geometry into ltcc and ltcc_cad systems so each uses the correct Geant4
  object factory, with CAD-local material and mirror definitions.

• Corrected FTTRK strip assignment to use the GEMC2 post-step position.

• Replaced the download-based install_fields.py with a copy from the magfield git-lfs subproject
  (subprojects/magfield.wrap + packagefiles/magfield/meson.build), erroring on unresolved LFS pointers,
  and added the use-fields-location option to bypass it, matching the clas12Tags source build.

• Added the include-subproject-install and include-subproject-tests options and wired them through the
  hipo-cpp and clas12-cmag subprojects via the hipo_install_option.patch and
  clas12_cmag_install_option.patch diffs, and gated the ccdb cmake install with set_install.

• Switched the clas12-cmag wrap from the local patch_directory overlay to the upstream v1.4 meson build
  plus the install-option diff, dropping the redundant packagefiles/clas12-cmag/meson.build.