The Cowbells package started as a green-field Geant4-based simulation of the cosmic-ray test stand constructed for research and development on water-based liquid scintilator at Brookhaven National Laboratory. It was extended to handle the configuration used for beam tests at the NASA Space Radiation Lab at BNL and then made general enough to support any, with some small development, novel detector configurations.
Cowbells is available from https://github.com/brettviren/cowbells.
- HepMC, Geant4, ROOT and a recent Python are needed.
- CMake is suggested if not strictly needed to install Geant4 and ROOT.
- IPython is recommended if any interactive Python sessions will be desired.
There are some methods available to assist in building cowbells and its dependencies.
- worch
- a waf-based build system. This is currently the recommended method. See ./doc/worch.org
- grinst
- a set of bash scripts. This is now obsolete but may still be usable. see ./doc/grinst.org
Cowbells is built with cmake. If you do not elect to build it automatically with one of the methods above it can be built by hand as described in this section. Also, see ./doc/worch.org for how to manually build cowbells against a worch-built set of dependencies.
cd /path/to/build/area/ cmake [-D...] /path/to/source_dir make
The locations for the dependencies may be given as -D directives. FIXME: give concrete example.
The simulation is configured through the command line and by one or
more configuration files written in JSONjson format. These files
can be written by any means but a suite of modules are provided by the
cowbells Python package to make generating them easier.
At top-level, the file schema is that of a single (anonymous) JSON dictionary. Each item of the dictionary has a key that determines the schema of the item and how the item’s data is used by cowbells. Multiple files can be given on the command line. If any section is found in more than one file the ordering of the files determine which section is used. The first one found “wins”.
Next, an overview of how to use the cowbells Python modules to make
produce configuration files is given. Following that is a description
of each configuration section.
The Python modules are used to build up a description of the detector geometry in memory in an organized and reusable fashion and to persist this description to the JSON configuration files.
The cowbells.geom module provides a submodule for each configuration
section related to geometry. It contains submodules and their classes
for materials, optical surfaces and properties and sensitive
detectors. These classes implement a very similar interface and
naming convention as used by the Geant4 geometry model. The
similarity is not complete but intends to cover the more commonly used
aspects.
Most of the classes implement the method .pod() which will emit a
“plain old data” (pod) structure that represents how the instance
has been configured. These pod structures can be aggregated and
finally fed to Python’s json module in order to produce the JSON
configuration files. These two tasks are handled by the next module
described.
Each of the geom.* submodule maintains a store data member which
collects every instance of its classes that are created. All stores
can be dumped to a JSON file with code like:
from cowbells import geom
# ... populate the geometry
fp = open("somefile.json", "w")
fp.write(geom.dumps_json())
fp.close()It is in this manner that most applications that produce configuration code are expected to operate.
The cowbells.builder= module defines and implements several
Builder classes. Instances of these create aggregate descriptions
based on input parameters of some major element of a detector
description.
The interface to a Builder is defined in the Builder base class and
is expected to be called by a top-level script or by a Builder that
aggregates other (finer grained) builders. Using a builder proceeds
in three parts:
- creating
- all builder constructors may take keyword parameters that modify their default behavior.
- building
- a top-level logical volume and all that it encompasses.
- placing
- the top logical volume must be placed in some parent volume by the caller.
The cowbells.default module provides pre-defined instances of some
cowbells.geom classes. These modules are used by calling special
functions which will populate the geometry with whatever objects they
define. The supported functions are:
optical()- define optical material properties. An optional material name may be given.
The configuration sections are described briefly. The provided
test_geom.py gives examples of the Python code needed. By running it
the file test_geom.json will be produced giving an example of a JSON
configuration file.
elements- list of elementary atoms
materials- list of aggregations of elements or other materials
shapes- list of shapes used for creating volumes
volumes- list of logical volumes each bringing together a shape and a material
placements- list of physical volumes each bringing together daughter and mother (unless its a world placement) volumes and a transformation between them
optical- list of optical properties associated with a named material
surfaces- list of optical surfaces
sensitive- list of sensitive detectors each associating a (Geant4 sensitive detector) class with a logical volume and a set of touchables.
Ultimately sensitive detectors are implemented by Geant4 C++ classes provided by cowbells. They record hits that occur in one or more placements of a given logical volume in to a named hit collection. In order to assign in which placement a hit occurred the sensitive detectors must be given a list of touchables. Each touchable is written as a path of placements from the world placement down to the placement of the sensitive volume. For example, the tub detector’s photocathode touchable may look like:
"pvWorld:0/pvWaterSample:0/pvAcrylicTubWindow:0/pvBialkaliPhotoCathode:0",
In addition to describing the geometry, JSON configuration files can describe these aspects:
physics- what physics to simulate
kinematics- how to produce the initial particle kinematics
The types of physics is simulate is specified by listing their code
names in the physics section:
{ "physics" : { "list" : ["em","op"] } }The supported codes are:
em- electromagnetic processes
op- optical processes
had- hadronic processes
The initial kinematics are specified by “type”. Depending on the type the rest of the configuration is interpreted. For example the usual particle “gun” is implemented and configured as in this example:
{ "kinematics" : {
"type" : "gun", "count" : 1,
"particle": "proton", "energy": "500*MeV"
"vertex": [0.0, 0.0, "-5.1*meter"],
"direction": [0.0, 0.0, 1.0] }}The main command line program produced by the Cowbells package is
cowbells.exe. Running it with no arguments produces a brief help
message.
Usage: cowbells [options] Options: --help Print usages and exit --output, -o <outputfile> Set output filename --interface, -u <interface>Set the user interface --kinematics, -k <kindesc> Set the kinematics descriptor --physics, -p <physics,list>Set the physics list --nevents, -n <#events> Set the number of events to generate
Some options, in particular the kinematics and physics, may be set in configuration files as well.
{{{fixme(This is a work in progress.)}}}
Set Geant4 UI.
{{{fixme(This feature is not complete.)}}}
The command line can override kinematics that may be otherwise set in a configuration file. They are specified in the form of a URL, for example:
cowbells.exe --kinematics \ 'kin://beam?vertex=0,0,0&name=proton&direction=1,0,0&energy=500'
Note, you will likely need to protect the characters ? and & from
your shell by encasing the option in quotes.
The command line can override any physics list that is otherwise provided in configuration files. For example with:
cowbells.exe --physics em,op,had [...]
Geant4 macro files can also be given on the cowbells.exe command
line. For example, a HepRepFile can be produced to display the
geometry and events in HepRAppheprapp using a macro file like:
/vis/open HepRepFile /vis/drawVolume /vis/scene/add/axes 0 0 0 100 mm /vis/viewer/flush /vis/scene/add/axes 0 0 0 100 mm /vis/scene/add/trajectories rich /vis/modeling/trajectories/create/drawByParticleID /vis/modeling/trajectories/drawByParticleID-0/set e- blue /vis/modeling/trajectories/drawByParticleID-0/set e+ cyan /vis/modeling/trajectories/drawByParticleID-0/set proton red /vis/modeling/trajectories/drawByParticleID-0/set neutron green /vis/modeling/trajectories/drawByParticleID-0/set opticalphoton white /run/beamOn 1
and a command line like:
cowbells.exe -o td.root opts.json td.json heprepvis.mac java -jar /path/to/HepRApp.jar G4Data0.heprep
heprapp http://www.slac.stanford.edu/BFROOT/www/Computing/Graphics/Wired/
The “tub” detector is a simple cylinder with a window in the lid that
holds a thin photocathode sensitive detector. The gentubdet.py
script in the share/ directory will generate geometry configuration
for it. The sample and tub material and the tub lining color can be
specified. The if the file is not given the JSON text is sent to
stdout.
gentubdet.py [-h] [-s SAMPLE] [-t TUB] [-c COLOR] file
Placing the above physics and kinematics into a file opts.json one example is:
gentubdet.py -s Water -t Aluminum -c black td.json cowbells.exe -n 10 -o td.root opts.json td.json
The first run at NSRL with tub detectors consisted of these elements in the beam line:
| (o) - [] - [] - W V H1 T1 H2 T2 H3
W- beam window
V- hole-veto counter
Hn- hodoscope trigger counter #n
Tn- tub detector #n
{{{fixme(Hole-veto not yet implemented.)}}}
The elements are rotated so that the beam runs along the Z-axis. The
center of the first tub detector is the global origin. To generate
this geometry configuration file the gennsrl.py script is used.
gennsrl.py file cowbells.exe \ -k 'kin://beam?vertex=0,0,-510&name=proton&direction=0,0,1&energy=500' \ -p em,op -n 10 -o nsrl.root nsrl.json
{{{fixme(No command line hooks yet exist to change the sample material.)}}}