You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
9
+
10
+
- Layered tool design culminating in a modular execution policy and reference command-line interface program.
11
+
- A multi-threaded execution model constructed following the data flow programming paradigm.
12
+
- Plugin, factory and configuration subsystems.
13
+
- Components providing simulation, signal processing and physics reconstruction algorithms.
14
+
- Suite of abstract interface classes.
15
+
- Low level utility algorithms, data structures and streaming data I/O formats.
16
+
17
+
Additional "README" information is available in the WCT sub packages:
18
+
19
+
- [[file:apps/README.org][apps]]
20
+
- [[file:aux/README.org][aux]]
21
+
- [[file:cfg/README.org][cfg]]
22
+
- [[file:cuda/README.org][cuda]]
23
+
- [[file:gen/README.org][gen]]
24
+
- [[file:iface/README.org][iface]]
25
+
- [[file:img/README.org][img]]
26
+
- [[file:pgraph/README.org][pgraph]]
27
+
- [[file:pytorch/README.org][pytorch]]
28
+
- [[file:root/README.org][root]]
29
+
- [[file:sigproc/README.org][sigproc]]
30
+
- [[file:sio/README.org][sio]]
31
+
- [[file:tbb/README.org][tbb]]
32
+
- [[file:test/README.org][test]]
33
+
- [[file:util/README.org][util]]
34
+
- [[file:waft/README.org][waft]]
35
+
- [[file:zio/README.org][zio]]
36
+
37
+
See http://wirecell.bnl.gov/ for the home of Wire-Cell Toolkit documentation and news "blog".
8
38
9
39
10
40
* Installation
11
41
12
-
Wire-Cell Toolkit provides simple and automatic installation which
13
-
gives you, the installer, some options.
42
+
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.
14
43
15
44
** External software dependencies
16
45
17
-
The WCT dependency tree:
46
+
The WCT dependencies are curated and minimized with some required and some optional. Below shows the intra- and inter-package dependency tree:
18
47
19
48
[[file:wct-deps.png]]
20
49
21
-
Anything that the ~WireCellUtil~ package depends on is required. The
22
-
rest are optional. Missing optional dependencies will cause the
23
-
dependent WCT package to not be built.
50
+
Black arrows are library dependencies, blue are for applications and gray are for testing programs. They represent compile/link time dependencies.
51
+
52
+
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.
24
53
25
54
Some external dependencies have explicit minimum required versions:
26
55
27
56
- TBB (oneAPI) 2021.1.1
28
57
- Boost 1.75.0
29
58
30
-
You may provide the necessary external software dependencies in a
31
-
manner of your own choosing and some options include:
59
+
You may provide the necessary external software dependencies in a manner of your own choosing and some options include:
32
60
61
+
- Packages provided by your OS or built "by hand".
33
62
- [[https://github.com/WireCell/wire-cell-spack][Spack-based install]] automatically builds all (non-OS) externals and WCT itself
34
63
- Some WCT releases are built at FNAL as a UPS product named =wirecell=.
35
-
- Exploit the above with a [[https://github.com/WireCell/wire-cell-singularity][Singularity container and CVMFS]] (currently recommended)
64
+
- Exploit the above with a [[https://github.com/WireCell/wire-cell-singularity][Singularity container and CVMFS]].
36
65
37
66
** Developer Source
38
67
@@ -44,9 +73,7 @@ Developers check out =master= branch via SSH.
44
73
45
74
** User Source
46
75
47
-
Users typically should build a release branch, either the tip or a
48
-
tagged release on that branch. Tagged releases are shown on the [[https://github.com/WireCell/wire-cell-toolkit/releases][this
49
-
GitHub release page]].
76
+
Users typically should build a release branch, either the tip or a tagged release on that branch. Tagged releases are shown on the [[https://github.com/WireCell/wire-cell-toolkit/releases][this GitHub release page]].
50
77
51
78
Users may also anonymously clone in the usual way:
52
79
@@ -62,16 +89,13 @@ On well-behaved systems, configuring the source may be as simple as:
62
89
$ ./wcb configure --prefix=/path/to/install
63
90
#+END_EXAMPLE
64
91
65
-
Software dependencies which can not automatically be located in system
66
-
areas or via ~pkg-config~ can be manually specified. For a list of
67
-
options run:
92
+
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:
68
93
69
94
#+BEGIN_EXAMPLE
70
95
$ ./wcb --help
71
96
#+END_EXAMPLE
72
97
73
-
Here is an example where some packages are found automatically and
74
-
some need help and others are explicitly turned off:
98
+
Here is an example where some packages are found automatically and some need help and others are explicitly turned off:
75
99
76
100
#+begin_example
77
101
$ ./wcb configure \
@@ -89,69 +113,42 @@ some need help and others are explicitly turned off:
89
113
90
114
** Building
91
115
92
-
It is suggested to first build the code before running tests.
116
+
The libraries and programs may be built with:
93
117
94
118
#+BEGIN_EXAMPLE
95
-
$ ./wcb -p --notests
119
+
$ ./wcb
96
120
#+END_EXAMPLE
97
121
98
122
** Installing
99
123
100
-
To install the built toolkit and its configuration support files while
101
-
still avoiding the tests do:
124
+
To install:
102
125
103
126
#+BEGIN_EXAMPLE
104
-
$ ./wcb -p --notests install
127
+
$ ./wcb install
105
128
#+END_EXAMPLE
106
129
107
-
Optionally, the *reference* configuration and data files for one or more
108
-
supported experiments may be installed by giving naming them with the
109
-
~--install-config~ option. A name matches a sub-directory under
110
-
[[file:cfg/pgrapher/experiment/][cfg/pgrapher/experiment/]] or the special ~all~ name will install all.
130
+
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 [[file:cfg/pgrapher/experiment/][cfg/pgrapher/experiment/]] or the special ~all~ name will install all.
See [[file:tests/README.org]] for more details on testing.
137
144
138
145
* Release management
139
146
140
-
To make releases, the above details are baked into two test scripts
141
-
[[https://github.com/WireCell/waf-tools/blob/master/make-release.sh][make-release.sh]] and [[https://github.com/WireCell/waf-tools/blob/master/test-release.sh][test-release.sh]]. See comments at the top of each
142
-
for how to run them. These scripts can be used by others but are
143
-
meant for developers to make official releases.
144
-
145
-
* Meta
146
-
147
-
A new =wcb= build script is made from [[https://github.com/waf-project/waf][waf source]] via:
147
+
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~.
148
148
149
-
#+BEGIN_EXAMPLE
150
-
$ cd waf-tools
151
-
$ ./refresh-wcb -o /path/to/wire-cell-toolkit/wcb
152
-
$ cd /path/to/wire-cell-toolkit/
153
-
$ git commit -am "update wcb" && git push
154
-
#+END_EXAMPLE
149
+
To make releases, the above details are baked into two test scripts [[https://github.com/WireCell/waf-tools/blob/master/make-release.sh][make-release.sh]] and [[https://github.com/WireCell/waf-tools/blob/master/test-release.sh][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.
155
150
151
+
* Meta
156
152
153
+
Prior to 0.25.0, ~wcb~ was a custom version of [[https://waf.io][Waf]] and is now simply a copy of ~waf~. The customized tools are held in the [[file:waft/]] directory.
This package provides toolkit layers at the top of an application
8
+
stack. This includes
9
+
10
+
- main command line programs, in particular ~wire-cell~.
11
+
12
+
- a ~Main~ class used in CLI and other application interfaces (such as /art/).
13
+
14
+
- a few so called "apps" which are WCT components that provide a
15
+
high-level execution policy. See also ~TbbFlow~ in sub package ~tbb~
16
+
and ~Pgrapher~ in
17
+
18
+
* Programs
19
+
20
+
** ~wire-cell~
21
+
22
+
The ~wire-cell~ command line program provides a "reference" application
23
+
of the toolkit. It is a generic, "policy free" program that is fully
24
+
driven by configuration.
25
+
26
+
#+begin_src bash :results output
27
+
wire-cell --help
28
+
wire-cell --version
29
+
#+end_src
30
+
31
+
#+RESULTS:
32
+
#+begin_example
33
+
Command line interface to the Wire-Cell Toolkit
34
+
35
+
Usage:
36
+
wire-cell [options] [configuration ...]
37
+
38
+
Options:
39
+
-h [ --help ] produce help message
40
+
-l [ --logsink ] arg set log sink as <filename> or 'stdout' or 'stderr', a
41
+
log level for the sink may be given by appending
42
+
':<level>'
43
+
-L [ --loglevel ] arg set lowest log level for a log in form 'name:level' or
44
+
just give 'level' value for all (level one of:
45
+
critical,error,warn,info,debug,trace)
46
+
-a [ --app ] arg application component to invoke
47
+
-c [ --config ] arg provide a configuration file
48
+
-p [ --plugin ] arg specify a plugin as name[:lib]
49
+
-V [ --ext-str ] arg specify a Jsonnet external variable=<string>
50
+
-C [ --ext-code ] arg specify a Jsonnet external variable=<code>
51
+
-A [ --tla-str ] arg specify a Jsonnet top level arguments variable=<string>
52
+
--tla-code arg specify a Jsonnet top level arguments variable=<code>
53
+
-P [ --path ] arg add to JSON/Jsonnet search path
54
+
-t [ --threads ] arg limit number of threads used
55
+
-v [ --version ] print the compiled version to stdout
56
+
57
+
0.24.0-33-gf9d92c77
58
+
#+end_example
59
+
60
+
** ~wcsonnet~
61
+
62
+
The ~wcsonnet~ program is a thin wrapper around the Jsonnet library used to build WCT. It can be preferable to the standard ~jsonnet~ program for the following reasons:
63
+
64
+
- It uses the Go Jsonnet library which is substantially faster than the C/C++ library used by ~jsonnet~.
65
+
- It honors the ~WIRECELL_PATH~ to locate files.
66
+
67
+
#+begin_src shell :results output
68
+
wcsonnet --help
69
+
#+end_src
70
+
71
+
#+RESULTS:
72
+
#+begin_example
73
+
wcsonnet is a Wire-Cell Toolkit aware Jsonnet compiler
74
+
Usage: wcsonnet [OPTIONS] [file]
75
+
76
+
Positionals:
77
+
file TEXT Jsonnet file to compile
78
+
79
+
Options:
80
+
-h,--help Print this help message and exit
81
+
-o,--output TEXT Output file
82
+
-P,--path TEXT ... Search paths to consider in addition to those in WIRECELL_PATH
83
+
-V,--ext-str TEXT ... Jsonnet external variable as <name>=<string>
84
+
-C,--ext-code TEXT ... Jsonnet external code as <name>=<string>
85
+
-A,--tla-str TEXT ... Jsonnet level argument value <name>=<string>
86
+
-S,--tla-code TEXT ... Jsonnet level argument code <name>=<string>
87
+
88
+
#+end_example
89
+
90
+
** ~wcwires~
91
+
92
+
One of the main input configurations to many WCT algorithms is the
93
+
"wire geometry". This is typically an exhaustive list of wire (or
94
+
strip) endpoints and their channel and other identifiers. In many
95
+
cases, the "wires files" are provided with errors. They may not
96
+
follow correct ordering conventions or they may have poor precision in
97
+
wire endpoints. WCT provides a way to validate and correct the wire
98
+
geometry when a "wires file" is read in and ~wcwires~ provides this
99
+
functionality in a convenient command line interface.
100
+
101
+
#+begin_src shell :results output
102
+
wcwires --help
103
+
#+end_src
104
+
105
+
#+RESULTS:
106
+
#+begin_example
107
+
wcwires converts and validates Wire-Cell Toolkit wire descriptions
108
+
Usage: wcwires [OPTIONS] [file]
109
+
110
+
Positionals:
111
+
file TEXT wires file
112
+
113
+
Options:
114
+
-h,--help Print this help message and exit
115
+
-P,--path TEXT ... Search paths to consider in addition to those in WIRECELL_PATH
116
+
-o,--output TEXT Write out a wires file (def=none)
117
+
-c,--correction INT Correction level: 1=load,2=order,3=direction,4=pitch (def=4)
-f,--fail-fast Fail on first validation error (def=false)
120
+
-e,--epsilon FLOAT Unitless relative error determining imprecision during validation (def=1e-6)
121
+
122
+
#+end_example
123
+
124
+
125
+
* WCT ~Main~
126
+
127
+
WCT provides a C++ class called ~Main~ which may be used to easily integrate WCT functionality into other applications. The ~wire-cell~ program provides a command line interface to ~Main~. Likewise, the ~WCLS_tool~ in the ~larwirecell~ packages of LArSoft providse an /art/ / FHiCL interface to ~Main~.
128
+
129
+
* WCT "apps"
130
+
131
+
Finally, this package provides a number of simple WCT "apps" classes.
132
+
Typically, one or more "app" instance is used via ~Main~ to provide some
133
+
top-level execution. Provided here are ~ConfigDumper~ and ~NodeDumper~
134
+
which are more examples than useful. See ~TbbFlow~ from the ~tbb~ sub
135
+
package and ~Pgrapher~ from the ~pgraph~ package for the two most used
0 commit comments