Wire Cell Toolkit Manual

WCT source is composed of several packages (see section 5) and all source is available from the Wire Cell GitHub organization. Releases of each package are made and documented on GitHub (eg here) and can be downloaded as archives. However, using git to assemble a working source area is recommended and easier. Releases and development branches are handled slightly differently.

To obtain a release requires no GitHub authentication:

$ git clone --branch 0.5.x \
      https://github.com/WireCell/wire-cell-toolkit.git

This gets the tip of a release branch (the 0.5.x series in this example). A specific point release can then be checked out:

$ git checkout -b 0.5.0 0.5.0

To contribute new development to the toolkit, even as a “core” developer, it’s recommended to fork the wire-cell-toolkit repository on GitHub, do your work there and make GitHub Pull Requests (PR). This gives an opportunity for other developers to give a quick check on new code.

Core developers can nonetheless directly push to the central repository. It’s suggested to do so via an SSH authenticated clone:

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

Prior to building, the source must be configured to specify an installation location and provide options to direct how to find external software dependencies and/or to select which optional dependencies. More details on the build system are in ./waftools.html.

On systems where software dependencies can be auto-detected, the configuration step may be as simple as:

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

This will print the results of the attempts to detect required and optional dependencies. Missing but optional dependencies will not cause failure. See below for guidance on installing dependencies if this step fails or if desired optional dependencies are not found.

Dependencies may be automatically located if pkg-config is available and possibly by suitably setting the PKG_CONFIG_PATH environment variable. If automatic location fails then missing locations can be explicitly specified. The following shows an example where all externals are installed at a single location identified by the WCT_EXTERNALS environment variable (not, this variable has no other special meaning other than to make this example brief).

$ ./wcb configure \
   --prefix=/path/to/install \
   --boost-includes=$WCT_EXTERNALS/include \
   --boost-libs=$WCT_EXTERNALS/lib --boost-mt \
   --with-root=$WCT_EXTERNALS \
   --with-fftw=$WCT_EXTERNALS \
   --with-eigen=$WCT_EXTERNALS \
   --with-jsoncpp=$WCT_EXTERNALS \
   --with-jsonnet=$WCT_EXTERNALS \
   --with-tbb=$WCT_EXTERNALS

If the externals are not all in one directory then their locations must be accordingly specified individually.

It is suggested to first build the code before running tests.

$ ./wcb -p --notests

If there are build failures more information can be obtained by repeating the build with more verbosity:

$ ./wcb -vv

To install the build results into the location given by --prefix simply issue:

$ ./wcb install --notests

Tests are run by default by ./wcb unless --notests is given. Running the tests can take a while but should be run on new installations and after any significant development. The developers should not leave broken tests so any failure should be treated as important. However, some tests require proper user environment to run correctly. In particular, tests need to find some Wire-Cell configuration files and the executable programs and shared libraries of the external software dependencies need to be located. Below shows an example:

$ export WIRECELL_PATH=$HOME/dev/wct/wire-cell-data:$HOME/dev/wct/wire-cell-toolkit/cfg
$ export LD_LIBRARY_PATH=$HOME/dev/wct/install/lib:$HOME/opt/jsonnet/lib
$ ./wcb -p --alltests
...
execution summary 
  tests that pass 83/83
    ... 
  tests that fail 0/83 
'build' finished successfully (15.192s)

These other commands may be useful:

$ ./wcb clean          # clean build products
$ ./wcb distclean      # also clean configuration
                       # build with debug symbols  
$ ./wcb configure --build-debug=-ggdb3 [...]
                       # to save some time, just 
                       # rebuild the given test 
                       # and don't run any tests
$ ./wcb --notests --target=test_xxx
$ ./wcb --help         # see more options.

In the DIY mode, the installer is free to provide the third-party packages in any convenient way. Many of them are available on well supported operating systems such as Debian/Ubuntu. Homebrew for Mac OS X is not a core developer platform but may provide many. Redhat derived Linux distributions may find suitable package on EPEL. Most of the required packages are fairly easy to build from source.

However the installer decides to build in DIY-mode the WCT build system should be able to be given proper installation locations via the --with-* flags as described above. If it seems not to be the case, please contact the developers.

One mostly “turn key” sway to provide an environment for WCT development and running is to use Singularity containers possibly augmented with CVMFS. Instructions and support can be found in the wire-cell-singularity package.

Spack is a “meta build system” that runs the individual build systems that come with packages. It allows one to manage an ever growing installation area which can accommodate multiple versions of a package. It also comes with support for Environment Modules to handle your users’ setup of these packages or can make targeted release “views” of its package tree.

WCT provides a package wire-cell-spack which collects instructions and an Spack “repo” that builds WCT and its third-party dependencies. This leverages Spacks built-in “repo” to provide dependencies needed by WCT’s direct dependencies. Using it will tend to build packages that one may already have installed through the OS (eg, Python). However, this duplication should not add much to the overall build time which is automatic nor lead to any problems.

An installer that wishes to use wire-cell-spack to provide the dependencies should begin by following its README file.

Fermi National Accelerator Lab (FNAL) uses a user environment system similar to Environment Modules. It is typical to download binaries provided by FNAL, either manually of automatically via a CVMFS mount, and then use the UPS shell function setup to configure a user environment with many environment variables. For each package (“UPS product”) that is so setup there is a variable that gives the installation location. These can be used to provide suitable values for the --with-* flags to wcb as described above. The source provides a script waftools/wct-configure-for-ups.sh which may help run ./wcb configure in such an environment.

WCT label releases are made following a fixed procedure. Releases are labeled with the common three-number convention: X.Y.Z. These take the following semantic meanings:

X

a major release is made when developers believe some substantial milestone has been achieved or to being wholly new or a globally breaking development path.

Y

a minor or feature release is made when substantial new and in particular any breaking development is made.

Z

a bug release fixes problems without otherwise substantial changes.

Any new major or minor releases produce a new Git branch in each package. Only bug fixes are made to this branch. Where applicable, release bug fixes should be applied to master. Nominally, all development is on the master branch however developers are free to make their own feature branches. They are encourage to do this if their development is expected to be disruptive to other developers.

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.

WCT supports two related configuration file formats: JSON and Jsonnet. Of the two, JSON is more fundamental while the Jsonnet data templating language provides a powerful way to organize and construct complex configurations. Jsonnet files are compiled into JSON by WCT and the result is then fed to the WCT configurable components.

A user gives one or more configuration files to the wire-cell application each with a -c flag:

$ wire-cell -c myparameters.cfg [...]

If a relative path is given, the file will be searched for starting in the current working directory and then in each directory listed in a WIRECELL_PATH environment variable, if given. When multiple configuration are used, their top-level arrays are conceptually concatenated in the order on which they are given on the command line.

An example JSON configuration for a single component might look like:

[
   {
      "data" : {
         "clight" : 1,
         "step_size" : 0.10000000000000001,
         "tracks" : []
      },
      "name" : "",
      "type" : "TrackDepos"
   }
]

Here we see an array holding one element which is an object with the type, (instance) name and payload data= structure as described above. If wire-cell were to load this configuration it would create a default instance of the component type TrackDepos which happens to correspond to the C++ class WireCell::Gen::TrackDepos (see the simulation package manual for more information). This component is responsible for produces deposition (IDepo) objects using a simple linear source model.

The tracks array in this example is empty and no depositions would be produced. The user most certainly should specify a nonempty set of tracks. In principle, the user may produces a huge tracks array. WCT support bzip2 compressed JSON files (see the section on persistence in the util package manual).

As the complexity of a wire-cell job grows, hand crafting JSON becomes tedious and error prone. Splitting the files and/or using WIRECELL_PATH can provide some rudimentary means of organizing a large, complex configuration.

However, a user will quickly outgrow direct authoring of JSON files. An accomplished user will likely turn to some form of JSON generation using a more expressive language maybe by developing some scripts. Or, some part of a configuration may need to be extracted or converted from another source. For example, Geant4 steps might be extracted and formatted into a TrackDepos configuration as a long tracks array.

Another limitation is that any numerical quantities must be expressed in the base units used by the WCT system of units (see the section on units in the Utilities manual). This places a burden on the configuration author and is a source of error.

The user is free to generate JSON in any manner they wish as long as the result conforms to the required schema. However, WCT provides a second, more powerful JSON-like configuration file format which described next.

WCT provides support for configuration files following the Jsonnet data templating language. This language is evaluated to produce JSON. WCT can evaluation Jsonnet files directly. The user may also install the jsonnet command line program which is useful for validating Jsonnet files. Either the valid Jsonnet or the JSON it produces may be given to WCT.

To learn how to write Jsonnet in general, the user should refer to its documentation which is excellent. There are many ways to structure Jsonnet and the wire-cell-cfg package provides a number of examples. It also provides support files that can help the user craft their configuration in Jsonnet. In particular the WCT system of units and some common data structures used by WCT are exported to Jsonnet in wirecell.jsonnet. Some of this exported functionality is illustrated below.

WCT locates Jsonnet files as it does JSON files through the environment variable WIRECELL_PATH. Unlike JSON files, Jsonnet files may not be compressed.

The wire-cell-cfg package also provides support for popular LArTPC detectors. You can find these files under a directory named for the experiment (such as that for MicroBooNE).

Jsonnet’s command line program jsonnet is fast and gives good error messages. It’s often easiest to develop a Jsonnet configuration using it for periodic validating. Assuming the current working directory is the top of the WCT source then running the following:

$ jsonnet -J cfg cfg/uboone/fourdee.jsonnet

should reward you with a big screen full of JSON. You can then run wire-cell something like:

$ wire-cell -c uboone/fourdee.jsonnet

This relies on the WIRECELL_PATH to include the cfg/ directory as well as any other directories holding any configuration data files referenced by the configuration.

Install singlularity and cvmfs following this.

This step-by-setp guide showed an example of using wcdo. For more, refer this

Noise waveforms will be generated based on a voltage amplitude spectrum represented in the frequency domain. This amplitude will be sampled and abide by some fluctuation distribution and may have some parameters that allow for parametric scaling or other transformation so that the user may explore the results. For simplicity, the time domain noise waveforms will be produced given a fixed sample period and readout time which will also be configurable. It is assumed that the user arranges that these parameters, if needed elsewhere, are set consistently. (See Sec. 2).

Producing noise waveforms as described here require no other input data and in particular, none that would change over time or be a function of some “event” So, the component will follow the pattern of being a source of data. That is, waveforms will be produced on demand and in a manner which they are independent. Below will show how this pattern is realized.

Before starting coding up an implementation it is prudent to understand what software dependencies are required to develop it. Some trade-offs need to be understood. Relying on “external” 3rd party packages to perform the “heavy lifting” of the implementation can make that implementation easier to develop. However, adding dependencies increase the difficulty in installing and using the result on a wide variety of operating systems and system architectures.

Investigating dependencies before implementation also forces the developer to make an optimal decision that balances performance, support, documentation, ease of development, portability and a host of other qualifiers. Relying on whatever software happens to be familiar and available forgoes making this optimal choice.

One touchstone that has been made by the WCT developers is that the “core” packages of WCT shall not depend on ROOT. Depending on ROOT brings in many additional dependencies and this can limit, for example, usage on high-core architectures with limited RAM. ROOT is very useful, and indeed parts of WCT depend on it (test, I/O packages) but for a package to be considered “core” its library must not require ROOT. If a component requires ROOT or other package not accepted by the “core” packages then the component must be placed in an optional package (see Section 3.3.3).

For the noise source, the main functionality required is drawing random variables from an arbitrary distribution (the noise spectrum) and drawing from some conventional distributions (for the fluctuation). The spectrum can be provided through WCT configuration services and drawing from it is a simple algorithm based on forming the cumulative distribution that can be directly integrated. Pseudo random number generation can be done directly in C++ or when this ticket is closed the WCT pRNG interface.

While the implementer is free to develop their component in any manner they wish, if the component is to be distributed as part of the WCT then its code needs to be in some WCT package. For here, the main thing to note is that the util package is the lowest in the dependency tree, on top of it is iface (more on interfaces below) and above that are all the implementation packages. The developer must choose an existing package or elect to make a new one depending on two main criteria: what dependencies are required and what implementation category does the component satisfy.

For the noise waveform source, given the relative lack of dependencies and the fact that it provides a simulation, the wire-cell-gen package provides a suitable home. If no suitable package exists the developer can see Section 5 for details on WCT packages.

All major functionality, and indeed the defining characteristic of a WCT component is that it implements one or more WCT interfaces which are C++ abstract base classes. Each interface defines some number of methods that the implementation must provide.

More information is in the Section 4.3 but for here, what is needed is that there are several categories of interfaces. First, any set of related methods can be grouped into an otherwise anonymous interface. One special interface is IConfigurable which is used if the implementation wishes to receive user-provided configuration information. Another category contains the interfaces inheriting from INode. An implementation inherits from one of these if it will participate in the 6 paradigm as implemented by WCT. Or, more generally, if the component is expected to share or pass “event” data (but really any data) with other component.

The noise waveform source requires configuration and will be an IFrameSource as it will produce frames of “traces” (waveform segments). As development progresses, it may come to light that portions of the implementation are general and are factored into separate classes which themselves may be accessed via an Interface.

Developing the noise source component begins with a header file which ties together the interfaces through inheritance, declares the interface methods to be implemented and any private methods and data the implementation may need. Following the layout conventions this header is placed in gen/inc/WireCellGen/NoiseSource.h. Some features to note:

• use #ifndef/#define/#endif include protection
• place inside WireCell namespace and a subnamespace that names the implementation (Gen) in this case
• add methods for each interface. Due to the templating used in the node interfaces it’s not always obvious which methods must be implemented unless one follows their inheritence tree. However, most high level interfaces based on INode should provide a comment in their header file giving what to implement.

The implementation of a component, following the layout conventions this header, is placed in gen/src/NoiseSource.cxx.

Packages are broken up by their primary scope or if they hold implementation requiring a major external software dependency. Each package should be named with a single, short word. If it is held in a separate repository, that is usually named wire-cell-<name>.

If a package produces a shared library it should be named in CamelCase with a prefix WireCell. For example the gen package produces a library libWireCellGen.so. As a plugin name or an entry in the build system, the lib and .so are dropped. If the package has public header files to expose to other packages they should use this same name for a subdirectory in which to hold them. Package layout is described move below.

Some of the C++ packages are designated as core packages. These include the packages providing the toolkit C++ structure (described later in this document) as well as the reference implementations (eg, gen, sigproc). These packages have strict requirements on what dependencies may be introduced and in particular their shared libraries are not allowed to depend on ROOT (although their apps and tests are, see sections 4.1.3 and 4.1.4).

The base package is util and it must not depend on any other WCT package. The next most basic is iface and it must not depend on any other WCT except util. Core implementation packages such as gen or sigproc may depend on both but must not depend on each other.

Third-party implementation packages may be developed outside of WCT. They are free to mimic WCT packages and of course depend on WCT and WCT itself shall not depend on them. They should not make use of the WireCell:: C++ namespace.

The WCT package layout and file extensions must follow some conventions in order to greatly simplify the build system. In the description below, WireCellName is as described above.

src/*.cxx

C++ source file for libraries with .cxx extensions or private headers

inc/WireCellName/*.h

public/API C++ header files with .h extensions

test/test_*.*

unit tests. C++ programs named like test_*.cxx will be built and run as will any test_*.{py,sh},

apps/*.cxx

main application(s), one appname.cxx file for each app named appname. Apps should be limited in number and code. WCT provides a single wire-cell main application as a CLI to the shared libraries.

In the root of each C++ package directory must exist a file called wscript_build. It typically consist of a single line with a method call like:

bld.smplpkg('WireCellName', use='...')

The bld object is automagically available. If the package has no dependencies then only the name is given. Most packages will need to specify some dependencies via use or may specify a different list of dependencies just for any applications (using app_use) or for the test programs (via test_use). Dependencies are transitive so one must only list those on which the package directly depends.

Fixme: make a script that generates a dot file and show the graph.

The wire-cell-toolkit provides a monolithic view of all the core WCT packages. It is maintained using git subrepo and this is transparent to users and most developers. To actually build WCT see the section on toolkit installation (section 1)

A new core WCT code package may be initially developed outside of wire-cell-toolkit proper and added via git subrepo or it may be created simply as a sub-directory of wire-cell-toolkit.

$ mkdir <name>
$ echo "bld.smplpkg('WireCell<Name>', use='WireCellUtil WireCellIface')" > <name>/wscript_build
$ emacs wscript
$ git commit -a -m "Start code package <name>"

Replace <name> with your package name. You can create and commit actual code at this time as well following the layout in 4.1.3. See section 5.5.3 for how to modify the wscript file.

• Base indentation should be four spaces.
• Tabs should not be used for indentation.
• Opening braces should not be on a line onto themselves, closing braces should be.
• Class names should follow CamelCase, method and function names should follow snake_case, class data attributes should be prefixed with m_ (signifying “member”).
• Doxygen triple-slash /// or double-star /** */ comments must be used for in-source reference documentation.
• Normal comments may be used for implementation documentation.
• Interface classes and their types and methods must each have a documenting Doxygen comment.
• Header files must have #ifndef/#define/#endif protection.
• The C++ using namespace keyword must not be used at top file scope in a header.
• Only headers defining symbols required by a file should be included.
• Any #include needed in an implementation file but not required by the corresponding header file should not be in the header file.

• All C++ code part of WCT proper and which may be accessed by other packages (eg, exported via “public headers”) must be under the WireCell:: namespace.
• WCT core code (util and iface packages) may exist directly under WireCell:: but bare functions must be in a sub namespace.
• Non-core, WCT implementation code (eg contents of gen package) must use secondary namespace (eg WireCell::Gen::).
• Any third-party packages providing WCT-based components or otherwise depending on WCT should not use the WireCell:: namespace.

• Configuration parameter names should follow snake_case.

Direct calling of utility functions and concrete objects.

Concrete components.

Using NamedFactory.

Using abstract DFP. A whole section on 6 is also available.

WCT wire-cell command line interface and the Main app it uses has support for adding sinks, optionally with levels (default is “trace”), setting the default level of all loggers and setting the level of specific loggers by name. The --help output gives a summary of what functionality the CLI provides. The Main app class can do similar and developers may see its header file.

[sl7kc]bviren@hierocles:wct> wire-cell --help
...
  -l [ --logsink ] arg  log sink, filename or 'stdout' or 'stderr', if added 
                        ':level' then set a log level for the sink
  -L [ --loglevel ] arg set lowest log level for a log in form 'name:level' or 
                        just 'level' for all (level one of 
                        error,warn,info,debug,trace)

The following example:

$ wire-cell -L trace -L pgraph:info -l stdout:info -l verbose.log:trace -c ....

will cause:

• the default logger level to be set down to trace from the default debug
• the pgraph logger will be raised to info to make it more quiet
• everything at info and above will be printed to stdout
• everything at trace and above will be printed to the file verbose.log

In this example:

$ wire-cell -c ....

The only thing that should print to the console are messages from wrongly programmed library code which is violating the “no iostream” rule.

The use of “bare” C++ std::cout or std::cerr is strongly discouraged in all WCT library code although they may be used in unit tests where convenient. Instead, WCT library code should use either an explicit logger object or the default logger.

There is some overhead in getting a logger so one should not be created deep in some loop. Instead, a component class should hold a logger as a class data member and initialize it in its constructor. For example:

class MyComponent : public ISomething {
    Log::logptr_t log;
public: // ...
};

Then in the constructor you would initialize something like:

MyComponent::MyComponent(...) 
    : log(Log::logger("myname"))
{
    // the constructor body
    log->debug("I created a MyComponent at {:p}", (void*)this);
}

The "myname" is the name of the logger and allows the logger to be shared by other objects. It is through this name that the user may control logger log levels. For now, the convention is to chose a short name that represents the package providing the code or the codes major functionality. Here are some names currently used:

wct

the base or default logger

glue

any pgraph node which doesn’t do much but provide network topology patterns (split, join, fanout/fanin, etc).

io

provides some file input/output node

sim

provides a simulation component (ie, from the misnamed wire-cell-gen package)

geom

provides some detector geometry related component

sys

core WCT system code/components (main, plugins, etc)

New names are allowed but proliferation should be avoided. Please add any new ones to this list.

Each logger provides a method with the same name as a level that code may call to produce a message at that level. These logger level methods take a string and variadic arguments. The string may include formatting codes used by fmt (provided by spdlog). See fmt syntax page for details.

log->trace("MyComponent: deep inside some loop with x={} and ptr={:p}", x, ptr);
log->debug("MyComponent: a once per event call with frame {}", frame->ident());
log->info("loading very important data config file {}", filename);
log->warn("you asked to drift {} depos way outside the detector, hope you know what you are doing", ndropped);

log->error("Called pass EOS {} times", ++neos);
return neos > 1;

THROW(ValueError() << errmsg{"divide by zero error"});
log->critical("This is fine.  *watches fire*");

By definition the debug and trace level messages may be prodigiously produced. Even if these levels are turned off (see blow) their calls are still made. To avoid wasting CPU on useless operations deep inside some loop these calls maybe compiled away if wrapped in CPP macros. Consider using them for at least trace. Eg:

void MyComponent::method() {
    for (...) {
        SPDLOG_LOGGER_TRACE(log, "This message may not even be compiled in");
    }
}

Of course, never place code with side effects inside such CPP macros.

The final code usage pattern is that of the default logger. No explicit logger object is needed which means all messages sent to it can not be disentangled when setting various levels. If one code sprays very verbose messages at info level there is no way to filter them out that will not also remove less verbose ones. Thus, this logger should be used sparingly and only in code where creating a named logger is somehow prohibitive. If used, extra care should be taken not to violate the suggested semantic meaning to the levels which was given above. With those caveats given, to use the default loggers call functions provided directly by spdlog:

using spdlog::debug;
// ...
void myfunc() {
    debug("my func is called");
    for (const auto& obj : giantarray) {
        spdlog::trace("super noisy message with obj {}", obj);
    }
}

WCT, being a toolkit, is meant to be integrated into a larger application or framework. These code bases often provide their own logging system. The choice of including spdlog to provide the WCT logging system was in part made to provide a mechanism by which it could also be integrated into whatever logging system the “host” code base may provide.

If the “host” also uses spdlog then integration is trivial. If it uses some other logging system then integration can be done by developing an spdlog sink which forwards message to the host’s equivalent of a logger. See the spdlog wiki entry on implementing custom sinks for instructions.

Another solution to integrate WCT logging with that of the “host” code base is to simply do nothing. The spdlog console output will naturally multiplex with any that the host may produce. However, users likely must take care to not use the same file to sink both logging systems.

It’s just a “normal” Python package. Use your favorite method, such as

$ virtualenv --system-site-packages venv
$ source venv/bin/activate
$ git clone https://github.com/WireCell/wire-cell-python.git
$ cd wire-cell-python/
$ python setup.py develop  
$ wirecell-sigproc --help

A number of python command line programs are provided. They are typically named like:

wirecell-<name>

Where <name> is one a package short name (eg, util, sigproc, gen).

All use the same command line interface (CLI) module (Click) so have similar usage. In particular, run the program without any arguments to get a help screen.

Describe units.

Describe support for persistent files including compression and location.

….

tbd

tbd

tbd

Depositions (IDepo data objects, aka depo) are provided by IDepoSource components. A single depo is provided on each call to the source and are expected to be produce in strict time order. In general a depo represents a 2D distribution (ie, Gaussian) of drifting electrons spread in longitudinal and transverse directions. A depo may be confined to a single point where the two extents of the distribution are zero.

The IDepoSource components adapt to external sources of information about initial activity in the detector. These sources may provide \(dE\) and \(dX\) in which case two models can be applied to produce associated number of ionized electrons. The external source may provide only \(dE\) in which case the number of ionized electrons will be calculated for the deposition on the assumption that the particle is a MIP. Finally, the ionization process may be handled by the external source and the number of electrons may be given directly.

The IDrifter components are responsible for transforming a depo at one location and time into another depo at a different location and time while suitably adjusting the number of ionization electrons and their 2D extents. Each call of the component accepts a single depo and returns zero or more output depos. Input depos are assumed to be strictly time ordered and each batch of output depos likewise. In general a drifter must cache depos for some length of time in order to assure it has seen all possible depos to satisfy causality for the output.

The field and electronics response of the detector is calculated in an IDuctor component. This is typically done by accepting depos at some input plane or response plane. Up to this plane, any drifting depo is assumed to induce a negligible detector response. For drifting beyond this plane some position dependent response is applied (ie, a field response calculated by 2D Garfield or 3D LARF). Each call to an IDuctor components accepts one depo and produces zero or more frames (IFrame data object). In general an IDuctor component must cache depos long enough to assure the produced frames satisfy causality. Output frames may be sparse in that not all channels may have traces (ITrace data objects) and in any given channel the traces may not cover the same span of time. The unit for the waveforms in the frame depend on the detector response applied. If field response alone is applied then the waveform is in units of sampled current (fixme, check code, it may be integrated over tick and thus charge.) If both field and electronics response is applied the waveform is in units of voltage.

An IDigitizer component applies a transformation to the waveform, typically but not necessarily in order to truncate it to ADC. These components are functional in that each call takes and produces one frame. Even if truncating to ADC the frame is still expressed as floating point values.

t.b.d.

Right now, frames can be summed by a bare function FrameUtil::sum(). This is better put into a component.

The gen package provides high-level IApplication components. Primarily, these provide aggregation of the various components described above (and others). The aggregation is conceptually of the form of a call graph which connects outputs of components to inputs of others. This aggregation is hard-coded so that the application determines the connectivity of the resulting execution graph.

Fourdee

provides a simple linear drift simulation chain from depos to digitized frame and with noise included. Only a single detector response is allowed and a single frame with signal and noise summed together is produced. (Aside: the “dee” stands for the various components with names starting with “D”.)

Multidee

provides a drift simulation that takes depositions through multiple paths and which produce multiple semantically different frames for the same set of depositions. The overall execution graph is shown in the figure below. The DepoFanout represents sending the same depo to multiple Ductor components. The MultiDuctor will apply particular detector response depending on where the depo is (measured in wire-space). This can be used to emulate MicroBooNE’s shorted wires. A second pointer to a depo goes into the “truth” Ductor which has a set of field response functions that produce some kind of “true” signal waveforms from the input depositions (eg, a simple Gaussian smearing instead of bipolar/unipolar field response). Finally, each frame is sunk for output by the MultiFrameSink which is just an IFrameSink that collates based on frame identifier numbers.

The wcb command bundles some optional Waf tools which are not included in the default version of the waf command. In case new versions of Waf or new tools are needed it can be recreated like this:

$ git clone https://github.com/waf-project/waf.git
$ cd waf/
$ ./waf-light --tools=compat15,doxygen,boost,bjam
$ cp waf /path/to/wire-cell-toolkit/wcb
$ cd /path/to/wire-cell-toolkit
$ git commit [...]

A number of Waf tools are provided in the tools/ subdirectory. They provide Python modules for each software package which is a required or optional dependency and which is not already covered by Waf itself. New dependencies can be added by using existing modules as examples. It is the smplpkgs.py module which handles the building of the WCT packages themselves. The wcb.py module is used as a simple aggregate of all the other modules. It is this that is loaded by the main wscript.

The wscript file directs all aspects of building WCT. It locates core WCT packages automatically so generally does not require modification to add new externals or new WCT core packages. However, it does contain hand-wired code to disable certain packages if their dependencies are not found.

Garfield 2D is used to calculate various things:

• the electrostatic or drift field near the wire planes
• electron drift paths through this field starting from an array of points at a (nominal) fixed drift distance and terminating on an electrode
• the Shockley-Ramo weighting field for one central wire of each wire plane
• the instantaneous current in each central wire separately for each drift path and regularly sampled over time.

The Garfield 2D user is free to pick the array drift path starting points however, a choice was made for initial field calculations and processing of Garfield 2D output assumes it holds. In particular:

• The drift paths all start with a fixed “X” coordinate value
• There is one drift path exactly aligned with each wire in the transverse direction.
• There is one drift path on one side of each wire starting exactly at the transverse midpoint with its neighbor
• There are four more equal spaced drift paths between these two.

These paths are said to start at impact positions. These impact positions extend across the entire transverse domain, bounded by one half wire pitch below the lowest wire and one half pitch above the highest wire. The impact positions where Garfield 2D paths start represent half of the total. The remaining half are defined through symmetry.

WCT provides a Python module to assist in generating a WCT field response file in compressed JSON format. It also is responsible for filling in missing drift paths, correcting any vagaries, normalizing units.

The main entry point into the Garfield 2D support is:

import wirecell.sigproc.garfield as garfield

The next section gives some detailed examples of use and subsequent ones give some plots.

This is from the ub_10 data set.

Taking raw Garfield output shows, apparently, two electrons were drifted per path. It’s unclear why it’s slightly more than 2.0 electrons of charge though.

import wirecell.sigproc.garfield as garfield
dat = garfield.load("/opt/bviren/wct-dev/share/wirecell/data/ub_10.tar.gz")
w = [r for r in dat if r.impact == 0 and r.region == 0 and r.plane == 'w'][0]
sum(w.response)
# -> -0.020265450377670812
w.times[1] / units.us
# -> 0.1
sum(w.response) * w.times[1] / units.coulomb
# -> -3.2468828093569448e-19
sum(w.response) * w.times[1] / units.eplus
# -> -2.0265450377670811
w0 = [r for r in dat if r.region == 0 and r.plane == 'w']
len(w0)
# -> 6
w0[0].region
# -> 0
sum(w0[0].response)/units.microampere
# -> -3.2577267395296085e-06
[sum(w.response)*w.times[1]/units.eplus for w in w0]
# -> [-2.033313287245619,
#     -2.0184390655262097,
#     -2.061704680164814,
#     -2.057934020579546,
#     -2.0501410482117408,
#     -2.0265450377670811]

Modify garfield.load() to normalize all responses so that this last array averages to 1.0. After that change:

[sum(r.response)*r.times[1]/units.eplus for r in dat2 if r.region == 0 and r.plane == 'w']
# -> [0.99606489937379161,
#     0.98877842254157267,
#     1.0099730708830847,
#     1.0081259272658833,
#     1.0043083619718129,
#     0.99274931796385024]
sum([sum(r.response)*r.times[1]/units.eplus for r in dat2 if r.region == 0 and r.plane == 'w'])/6.0
# -> 0.99999999999999944

Same region 0 average in units of eplus for U is -6.9e-3 and for V is -5.5e-3.

Some critical validation plots can be made from the command line using the wirecell-sigproc program. In the examples below it is assumed, for brevity that the Garfield 2D data set is available via the $G2D environment variable set for example like:

$ export G2D=/opt/bviren/wct-dev/share/wirecell/data/ub_10.tar.gz

The WCT does not directly read Garfield 2D data sets but instead requires the information to be compiled into a single, compressed JSON file. This is done like:

$ wirecell-sigproc convert-garfield $G2D garfield-1d-3planes-21wires-6impacts-v5.json.bz2

FIXME: distribution of these data files needs some formal mechanism. For now, they may be available here: http://www.phy.bnl.gov/~bviren/tmp/wctsim/wct-dev/share/wirecell/data/.

As of WCT 0.6.1 and LArSoft 6.48.0 there is support for running WCT inside of art in an extensible and maintainable manner. The software that provides this integration is maintained in the LArSoft package larwirecell maintained in FNAL’s Redmine (github mirror).

The sections below cover the integration software design, special issues relating to configuration inside of art, how to prepare an art runtime environment which includes WCT and how to develop WCT in the context of art as the driving application.

The design of the integration software is summarized in the following UML diagram.

The classes in blue are in larwirecell. The dark blue module and the WCLS tool classes are implementations of art concepts and remaining follow WCT. A WireCellToolkit art module is provided in larwirecell. Instances of this class may be used directly or it can serve as a reference example. Regardless of the module, the WCT processing is delegated to the WCLS tool. It is effectively a copy of the wire-cell program but written to be called as an art tool instead of from a command line. In the section 2 below it’s shows that it shares most of the same options as wire-cell.

The WCLS tool is responsible for WCT-side configuration and execution and special LS-side execution. This latter entails calling the implementations to a LS-specific interface class IArtEventVisitor. These objects likely also implement some other common WCT interface. Two examples of the roles these objects have are:

data converter

translating data products from LS to WCT, or vice versa.

service facade

providing WCT access to some LS service.

Bracketed by these “two (inter)faced” converter objects are the usual “core” components of the WCT job. Shown in the figure are two frame filters implementing noise filtering and signal process, respectively. Not shown is the WCT “application” object which is responsible for aggregating the top level components and marshalling data through them (in this example this would be the class sigproc::Omnibus=).

The bulk of configuring WCT to run inside of LS is identical to what it would be to run from the wire-cell command line. The only difference pertains to:

• configuring art and LS components
• configuring WC/LS converter components

It is recommended, and indeed easy, to structure the WCT configuration so that the parts that depend on the WC/LS layer are factored out from those that depend on LS-side WCT components.

In addition there is the need to provide a family of job-independent WCT configuration “data” files. These include, for example, the special field-response functions WCT uses. They are provided by the wire-cell-data package.

The FHiCL fragment to configure the WireCellToolkit art module and its WCLS tool for noise filtering and signal processing would look something like:

  physics :{
     producers: {
        nfsp : {
           module_type : WireCellToolkit
           wcls_main: {
              tool_type: WCLS                             # (1)
              apps: ["Omnibus"]                           # (2)
              plugins: ["WireCellGen", "WireCellSigProc", # (3)
                        "WireCellSio", "WireCellLarsoft"]
              configs: ["uboone-nf-sp.jsonnet"]           # (4)
              inputers: ["wclsRawFrameSource",            # (5)
                         "wclsChannelNoiseDB"]
              outputers: ["wclsCookedFrameSink"]          # (6)
              params: {                                   # (7)
                 detector: "uboone"
              }
          }
        }
     }
     # ...
}

Notes which refer to the parenthetical numbers:

1. Declare that the configuration applies to an art class tool of type WCLS.
2. The apps list defines WCT application objects which are responsible for performing top-level execution. They are somewhat conceptually equivalent to art modules.
3. The plugins list defines WCT plugin libraries in which WCT may find definitions of component classes. A plugin name matches its library name with the leading lib and trailing extension remove. The WireCellLarsoft plugin contains WC/LS integration components from the larwirecell package.
4. The configs list gives an ordered list of all top-level WCT configuration files. As shown, these are in Jsonnet data tempting but may also be in JSON. They, like all WCT configuration files (including job-independent configuration “data” files) are found via the WIRECELL_PATH environment variable. More information on WCT configuration is in 2.
5. The inputers list IArtEventVisitor components that should be called before the WCT application objects are executed. Here, the component which converts from LS’s raw::RawDigit collections to WCT’s IFrame instances is included. The second a channel noise DB object which inherits from WCT’s OmniNoiseChannelDB and augments the fully but statically configured information with some portion that is taken dynamically from LS services.
6. The outputers list is interpreted identically to inputers but its components are executed after the WCT app objects.
7. The params dictionary may define WCT configuration parameters that are referenced by the Jsonnet files that are loaded. This allows the bulk of the configuration to be made more generic by pushing out meta-parameters to the end user.

WCT components are named in the apps, inputers and outputers parameter lists. As shown, just their WCT component “type” names are given (these are not necessarily their C++ class names, but are usually similar). Like all references to components in WCT configuration, these may be specialized by giving an optional “instance” name. This allows for multiple instances of the same component class which may then be configured uniquely. Again, more details on WCT configuration are in 2.

Running WCT inside of art entails running art which means setting up a runtime environment in the “Fermilab way”. This requires obtaining binary packages (“UPS products”) from Fermilab for your host OS. If supported, this can be done in a number of ways.

The challenge to do development on WC/LS integration code is that the larwirecell expects WCT to be provided as a released and built UPS product. Development of course requires constant rebuilding and adding releases and full UPS product building is prohibitive. The solution is to cheat and produce what looks like an installed wirecell UPS product area into which the development WCT code is directly built.