HOWTO run hdgeant simulations using ccdb geometry

Until now, the hdgeant simulation depended on having the hdds geometry installed on a local filesystem. The geometry is represented by a set of linked xml files, with the top-level file (usually named main_HDDS.xml) referencing separate xml files for each subsystem as entity references. All of these xml files are now managed under a standalone github repository at https://github.com/JeffersonLab/hdds and installed locally at $HDDS_HOME within the standard GlueX environment. The files in the master branch of this repository are intended to represent the current operating state of the GlueX detectors and beamline. Other branches exist to provide a description of non-standard configurations, or exceptional setups that were present for special run periods.

Normally selection of the desired geometry to be used in a simulation takes place at the time the hdgeant binary is built. The standard build scripts first run "scons install" in HDDS_HOME, which translates the hdds geometry description into geant3-compatible functions, and builds them into the libhdds.so library. This library then gets linked in when the hdgeant executable is built during the "scons install" step under halld_sim. If you run hdgeant without special arguments (see below), that is the geometry that is used in the simulation.

There is a second method for feeding geometry information to hdgeant, which allows the simulation geometry to be selected at run time. This method is activated by the commannd-line option -xml. Here is an example of how this might be used.

$ hdgeant -xml=/home/jones/my_private_geometry/main_HDDS.xml

If the -xml option is present then any path supplied after the = argument is searched for the given main_HDDS.xml top-level hdds geometry file, and any subsystem xml files that it includes. Since the commandline argument is discovered at run time, the hdgeant application must do on-the-fly translation from xml to geant3 library code, compile the code into a dynamic library, and load the dynamic library into the runtime context. This capability has existed for a long time now, but it was not widely used because the xml files one would like it to reference are usually the same as the ones in HDDS_HOME, which were built into the hdgeant executable from the start and enabled by default. Only when users want to customize their own private geometry is this option generally recommended.

This recently changed with the introduction of the DIRC to the master branch of the JeffersonLab/hdds repository. Now anyone who wants to simulate a run prior to Spring 2019 needs to create a custom version of the hdds geometry without the DIRC present, and include -xml=/path/to/main_HDDS_pre2019.xml on the hdgeant commandline. This behavior is different from what is obtained with hdgeant4, where the geometry is fetched directly from ccdb, with the version selected automatically according to the run number. With the latest release of halld_sim, a similar feature is now available in hdgeant, where the geometry is taken from ccdb, with the version selected by run number. To activate this mode, you need to provide the -xml commandline argument with a specially formatted string in the path argument.

$ hdgeant -xml=ccdb://GEOMETRY/main_HDDS.xml,run=NNNNNN

where NNNNNN is the run number corresponding to the geometry you would like to simulate. Note that this entire string must be used verbatim as shown, with the only change being the run number NNNNNN. Also note that, unlike hdgeant4, this mechanism pays no attention to environment variables JANA_GEOMETRY_URL and JANA_CALIBRATION_CONTEXT, using only the string specified on the commandline in the lookup of the geometry information in ccdb.

Please direct any problem reports or questions to richard.t.jones(at)uconn.edu