Wire-Cell Toolkit

Table of Contents

Welcome to the Wire-Cell Toolkit (WCT) source repository at https://github.com/wirecell/wire-cell-toolkit.

1. Overview

The WCT is a multi-faceted, high performance software project developed for liquid argon time projection chamber (LArTPC) simulation and data processing. Some features of WCT include:

  • Layered tool design culminating in a reference command-line interface program.
  • A multi-threaded execution model constructed following the data flow programming paradigm.
  • Plugin, factory and configuration subsystems.
  • Components providing simulation, signal processing and physics reconstruction algorithms.
  • Suite of abstract interface classes.
  • Low level utility algorithms, data structures and streaming data I/O formats.

Additional README information is available in the WCT sub packages:

See http://wirecell.bnl.gov/ for the home of Wire-Cell Toolkit documentation and news “blog”.

2. Installation

Wire-Cell Toolkit provides simple and automated installation while allowing you to adapt it so you may provide the required dependencies in a variety of ways.

2.1. External software dependencies

The WCT dependencies are curated and minimized with some required and some optional. Below shows the intra- and inter-package dependency tree:


Black arrows are library dependencies, blue are for applications and gray are for testing programs. They represent compile/link time dependencies.

The dependencies for the WireCellUtil package are required. The rest are optional. Missing optional dependencies, or ones specifically turned off, will cause the dependent WCT package to not be built.

Some external dependencies have explicit minimum required versions:

  • TBB (oneAPI) 2021.1.1
  • Boost 1.75.0

You may provide the necessary external software dependencies in a manner of your own choosing and some options include:

  • Packages provided by your OS or built “by hand”.
  • Spack-based install automatically builds all (non-OS) externals and WCT itself
  • Some WCT releases are built at FNAL as a UPS product named wirecell.
  • Exploit the above with a Singularity container and CVMFS.

2.2. Developer Source

Developers check out master branch via SSH.

$ git clone git@github.com:WireCell/wire-cell-toolkit.git wct

2.3. User Source

Users typically should build a release branch, either the tip or a tagged release on that branch. Tagged releases are shown on the this GitHub release page.

Users may also anonymously clone in the usual way:

$ git clone https://github.com/WireCell/wire-cell-toolkit.git wct

2.4. Configuring the source

On well-behaved systems, configuring the source may be as simple as:

$ ./wcb configure --prefix=/path/to/install

Software dependencies which can not automatically be located in system areas or via pkg-config can be manually specified. For a list of options run:

$ ./wcb --help

Here is an example where some packages are found automatically and some need help and others are explicitly turned off:

$ ./wcb configure \
        --prefix=$HOME/dev/wct/install \
        --with-jsonnet=$HOME/opt/jsonnet \
Removing submodule "dfp" due to lack of external
Removing package "tbb" due to lack of external dependency
Removing package "root" due to lack of external dependency
Removing package "cuda" due to lack of external dependency
Configured for submodules: apps, cfg, gen, iface, img, pgraph, ress, sigproc, sio, util
'configure' finished successfully (5.683s)

2.5. Building

The libraries and programs may be built with:

$ ./wcb

2.6. Installing

To install:

$ ./wcb install

Optionally, the reference configuration and data files for one or more supported experiments may be installed by giving naming them with the --install-config option. A name matches a sub-directory under cfg/pgrapher/experiment/ or the special all name will install all.

$ ./wcb --install-config=<name> install

2.7. Testing

Running the tests can take a while but are off by default. They may be run with:

$ ./wcb --tests

See tests/README.html for more details on testing.

3. Release management

WCT uses an X.Y.Z version string. While X=0, a 0.Y.0 version indicates a new release that may extend or break API or ABI compared to Y-1. A Z>0 indicates a bug fix to Z-1 which should otherwise retain the API and ABI. Bug fixes will be made on a branch rooted on 0.X.0 called 0.X.x.

To make releases, the above details are baked into two test scripts make-release.sh and test-release.sh. See comments at the top of each for how to run them. These scripts can be used by others but are meant for developers to make official releases.

4. Meta

Prior to 0.25.0, wcb was a custom version of Waf and is now simply a copy of waf. The customized tools are held in the waft/ directory.

Author: Brett Viren

Created: 2023-05-03 Wed 11:39