-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathmanual.html
3427 lines (2941 loc) · 258 KB
/
manual.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2019-09-13 Fri 09:21 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Wire Cell Toolkit Manual</title>
<meta name="generator" content="Org mode" />
<meta name="author" content="Brett Viren" />
<meta name="description" content="Documentation for the Wire Cell Toolkit for users, developers and installers."
/>
<meta name="keywords" content="C++, software toolkit, neutrino, liquid argon time projection chamber, LArTPC, drift simulation, field response, event reconstruction, waveform signal processing, 3D imaging, Brookhaven National Lab" />
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
.title { text-align: center;
margin-bottom: .2em; }
.subtitle { text-align: center;
font-size: medium;
font-weight: bold;
margin-top:0; }
.todo { font-family: monospace; color: red; }
.done { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #ccc;
box-shadow: 3px 3px 3px #eee;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: visible;
padding-top: 1.2em;
}
pre.src:before {
display: none;
position: absolute;
background-color: white;
top: -10px;
right: 10px;
padding: 3px;
border: 1px solid black;
}
pre.src:hover:before { display: inline;}
/* Languages per Org manual */
pre.src-asymptote:before { content: 'Asymptote'; }
pre.src-awk:before { content: 'Awk'; }
pre.src-C:before { content: 'C'; }
/* pre.src-C++ doesn't work in CSS */
pre.src-clojure:before { content: 'Clojure'; }
pre.src-css:before { content: 'CSS'; }
pre.src-D:before { content: 'D'; }
pre.src-ditaa:before { content: 'ditaa'; }
pre.src-dot:before { content: 'Graphviz'; }
pre.src-calc:before { content: 'Emacs Calc'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-fortran:before { content: 'Fortran'; }
pre.src-gnuplot:before { content: 'gnuplot'; }
pre.src-haskell:before { content: 'Haskell'; }
pre.src-hledger:before { content: 'hledger'; }
pre.src-java:before { content: 'Java'; }
pre.src-js:before { content: 'Javascript'; }
pre.src-latex:before { content: 'LaTeX'; }
pre.src-ledger:before { content: 'Ledger'; }
pre.src-lisp:before { content: 'Lisp'; }
pre.src-lilypond:before { content: 'Lilypond'; }
pre.src-lua:before { content: 'Lua'; }
pre.src-matlab:before { content: 'MATLAB'; }
pre.src-mscgen:before { content: 'Mscgen'; }
pre.src-ocaml:before { content: 'Objective Caml'; }
pre.src-octave:before { content: 'Octave'; }
pre.src-org:before { content: 'Org mode'; }
pre.src-oz:before { content: 'OZ'; }
pre.src-plantuml:before { content: 'Plantuml'; }
pre.src-processing:before { content: 'Processing.js'; }
pre.src-python:before { content: 'Python'; }
pre.src-R:before { content: 'R'; }
pre.src-ruby:before { content: 'Ruby'; }
pre.src-sass:before { content: 'Sass'; }
pre.src-scheme:before { content: 'Scheme'; }
pre.src-screen:before { content: 'Gnu Screen'; }
pre.src-sed:before { content: 'Sed'; }
pre.src-sh:before { content: 'shell'; }
pre.src-sql:before { content: 'SQL'; }
pre.src-sqlite:before { content: 'SQLite'; }
/* additional languages in org.el's org-babel-load-languages alist */
pre.src-forth:before { content: 'Forth'; }
pre.src-io:before { content: 'IO'; }
pre.src-J:before { content: 'J'; }
pre.src-makefile:before { content: 'Makefile'; }
pre.src-maxima:before { content: 'Maxima'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-picolisp:before { content: 'Pico Lisp'; }
pre.src-scala:before { content: 'Scala'; }
pre.src-shell:before { content: 'Shell Script'; }
pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
/* additional language identifiers per "defun org-babel-execute"
in ob-*.el */
pre.src-cpp:before { content: 'C++'; }
pre.src-abc:before { content: 'ABC'; }
pre.src-coq:before { content: 'Coq'; }
pre.src-groovy:before { content: 'Groovy'; }
/* additional language identifiers from org-babel-shell-names in
ob-shell.el: ob-shell is the only babel language using a lambda to put
the execution function name together. */
pre.src-bash:before { content: 'bash'; }
pre.src-csh:before { content: 'csh'; }
pre.src-ash:before { content: 'ash'; }
pre.src-dash:before { content: 'dash'; }
pre.src-ksh:before { content: 'ksh'; }
pre.src-mksh:before { content: 'mksh'; }
pre.src-posh:before { content: 'posh'; }
/* Additional Emacs modes also supported by the LaTeX listings package */
pre.src-ada:before { content: 'Ada'; }
pre.src-asm:before { content: 'Assembler'; }
pre.src-caml:before { content: 'Caml'; }
pre.src-delphi:before { content: 'Delphi'; }
pre.src-html:before { content: 'HTML'; }
pre.src-idl:before { content: 'IDL'; }
pre.src-mercury:before { content: 'Mercury'; }
pre.src-metapost:before { content: 'MetaPost'; }
pre.src-modula-2:before { content: 'Modula-2'; }
pre.src-pascal:before { content: 'Pascal'; }
pre.src-ps:before { content: 'PostScript'; }
pre.src-prolog:before { content: 'Prolog'; }
pre.src-simula:before { content: 'Simula'; }
pre.src-tcl:before { content: 'tcl'; }
pre.src-tex:before { content: 'TeX'; }
pre.src-plain-tex:before { content: 'Plain TeX'; }
pre.src-verilog:before { content: 'Verilog'; }
pre.src-vhdl:before { content: 'VHDL'; }
pre.src-xml:before { content: 'XML'; }
pre.src-nxml:before { content: 'XML'; }
/* add a generic configuration mode; LaTeX export needs an additional
(add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
pre.src-conf:before { content: 'Configuration File'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.org-right { text-align: center; }
th.org-left { text-align: center; }
th.org-center { text-align: center; }
td.org-right { text-align: right; }
td.org-left { text-align: left; }
td.org-center { text-align: center; }
dt { font-weight: bold; }
.footpara { display: inline; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.equation-container {
display: table;
text-align: center;
width: 100%;
}
.equation {
vertical-align: middle;
}
.equation-label {
display: table-cell;
text-align: right;
vertical-align: middle;
}
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
.org-svg { width: 90%; }
/*]]>*/-->
</style>
<link rel="stylesheet" type="text/css" href="styles/bigblow/css/htmlize.css"/>
<link rel="stylesheet" type="text/css" href="styles/bigblow/css/bigblow.css"/>
<link rel="stylesheet" type="text/css" href="styles/bigblow/css/hideshow.css"/>
<script type="text/javascript" src="styles/bigblow/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="styles/bigblow/js/jquery-ui-1.10.2.min.js"></script>
<script type="text/javascript" src="styles/bigblow/js/jquery.localscroll-min.js"></script>
<script type="text/javascript" src="styles/bigblow/js/jquery.scrollTo-1.4.3.1-min.js"></script>
<script type="text/javascript" src="styles/bigblow/js/jquery.zclip.min.js"></script>
<script type="text/javascript" src="styles/bigblow/js/bigblow.js"></script>
<script type="text/javascript" src="styles/bigblow/js/hideshow.js"></script>
<script type="text/javascript" src="styles/lib/js/jquery.stickytableheaders.min.js"></script>
<script type="text/javascript">
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
Copyright (C) 2012-2019 Free Software Foundation, Inc.
The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version. The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.
@licend The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
function CodeHighlightOn(elem, id)
{
var target = document.getElementById(id);
if(null != target) {
elem.cacheClassElem = elem.className;
elem.cacheClassTarget = target.className;
target.className = "code-highlighted";
elem.className = "code-highlighted";
}
}
function CodeHighlightOff(elem, id)
{
var target = document.getElementById(id);
if(elem.cacheClassElem)
elem.className = elem.cacheClassElem;
if(elem.cacheClassTarget)
target.className = elem.cacheClassTarget;
}
/*]]>*///-->
</script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
displayAlign: "center",
displayIndent: "0em",
"HTML-CSS": { scale: 100,
linebreaks: { automatic: "false" },
webFont: "TeX"
},
SVG: {scale: 100,
linebreaks: { automatic: "false" },
font: "TeX"},
NativeMML: {scale: 100},
TeX: { equationNumbers: {autoNumber: "AMS"},
MultLineWidth: "85%",
TagSide: "right",
TagIndent: ".8em"
}
});
</script>
<script type="text/javascript"
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_HTML"></script>
</head>
<body>
<div id="content">
<h1 class="title">Wire Cell Toolkit Manual</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#installation">1. Installation</a>
<ul>
<li><a href="#toolkit-installation">1.1. Toolkit installation</a>
<ul>
<li><a href="#source-code">1.1.1. Source code</a></li>
<li><a href="#configuring-the-source">1.1.2. Configuring the source</a></li>
<li><a href="#building-the-source">1.1.3. Building the source</a></li>
<li><a href="#install-built-code">1.1.4. Install the results</a></li>
<li><a href="#running-unit-tests">1.1.5. Running unit tests</a></li>
<li><a href="#other-build-commands">1.1.6. Other build commands</a></li>
</ul>
</li>
<li><a href="#runtime-environment">1.2. Runtime environment</a></li>
<li><a href="#installing-dependencies">1.3. Guide for installation of dependencies</a>
<ul>
<li><a href="#manual-externals-install">1.3.1. Manual Installation of Externals</a></li>
<li><a href="#singularity-cvmfs-externals">1.3.2. Singularity containers and CVMFS</a></li>
<li><a href="#spack-installed-externals">1.3.3. Automated Installation with Spack</a></li>
<li><a href="#using-externals-from-ups">1.3.4. Externals provided by UPS</a></li>
</ul>
</li>
<li><a href="#release-management">1.4. Release management</a>
<ul>
<li><a href="#release-versions">1.4.1. Release versions</a></li>
<li><a href="#branch-policy">1.4.2. Branch policy</a></li>
<li><a href="#branch-mechanics">1.4.3. Branch mechanics</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#configuration">2. Configuration</a>
<ul>
<li><a href="#configuration-introduction">2.1. Introduction</a></li>
<li><a href="#user-configuration">2.2. Configuration from a user point of view   <span class="tag"><span class="user">user</span></span></a>
<ul>
<li><a href="#configuration-file-formats">2.2.1. File formats</a></li>
<li><a href="#configuration-command-line">2.2.2. Basic command line</a></li>
<li><a href="#diving-into-json">2.2.3. Diving into JSON</a></li>
<li><a href="#json-limitations">2.2.4. Limitations of JSON</a></li>
<li><a href="#learning-jsonnet">2.2.5. Learning Jsonnet</a></li>
<li><a href="#configuration-for-specific-detectors">2.2.6. Specific detector support</a></li>
<li><a href="#jsonnet-command-line">2.2.7. Using the <code>jsonnet</code> command line program</a></li>
</ul>
</li>
<li><a href="#developer-configuration">2.3. <span class="todo TODO">TODO</span> Configuration from a developer point of view   <span class="tag"><span class="devel">devel</span></span></a></li>
</ul>
</li>
<li><a href="#howtos">3. Howtos</a>
<ul>
<li><a href="#install-wire-cell-with-singularity-container">3.1. Install wire-cell with singularity container</a>
<ul>
<li><a href="#a-singularity-and-cvmfs">3.1.1. A) singularity and cvmfs</a></li>
<li><a href="#b-wcdo">3.1.2. B) wcdo</a></li>
</ul>
</li>
<li><a href="#run-wire-cell-cli">3.2. Run <code>wire-cell</code> command line program</a></li>
<li><a href="#add-a-component">3.3. Add a new component class</a>
<ul>
<li><a href="#component-concept">3.3.1. Conceptual design</a></li>
<li><a href="#component-dependencies">3.3.2. Estimating dependencies</a></li>
<li><a href="#component-package">3.3.3. Selecting a package</a></li>
<li><a href="#component-interfaces">3.3.4. Selecting interfaces</a></li>
<li><a href="#component-header">3.3.5. Component header</a></li>
<li><a href="#component-implementation">3.3.6. Component implementation</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#internals">4. Internals</a>
<ul>
<li><a href="#toolkit-packages">4.1. Toolkit packages</a>
<ul>
<li><a href="#package-names">4.1.1. Names</a></li>
<li><a href="#package-dependencies">4.1.2. Dependencies</a></li>
<li><a href="#package-structure">4.1.3. Package structure</a></li>
<li><a href="#build-package">4.1.4. Build package</a></li>
<li><a href="#add-new-package-to-build">4.1.5. Adding a new code package</a></li>
</ul>
</li>
<li><a href="#coding-conventions">4.2. Coding conventions</a>
<ul>
<li><a href="#c++-code-formatting">4.2.1. C++ code formatting</a></li>
<li><a href="#c++-namespaces">4.2.2. C++ namespaces</a></li>
<li><a href="#configuration-conventions">4.2.3. Configuration Parameters</a></li>
</ul>
</li>
<li><a href="#interface-internals">4.3. Interfaces</a></li>
<li><a href="#component-internals">4.4. Components</a></li>
<li><a href="#configuration-internals">4.5. Configuration</a></li>
<li><a href="#execution-models">4.6. Execution Models</a>
<ul>
<li><a href="#ad-hoc-execution">4.6.1. Ad-hoc</a></li>
<li><a href="#execution-concrete-components">4.6.2. Concrete</a></li>
<li><a href="#execution-via-interfaces">4.6.3. Interface</a></li>
<li><a href="#dfp-execution">4.6.4. Data flow programming execution</a></li>
</ul>
</li>
<li><a href="#logging">4.7. Logging</a>
<ul>
<li><a href="#logging-cli">4.7.1. Logging Command Line Interface</a></li>
<li><a href="#logging-code">4.7.2. Logging Code Interface</a></li>
<li><a href="#logging-int">4.7.3. Logging Integration</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#packages">5. Packages</a>
<ul>
<li><a href="#pkg-python">5.1. <code>wire-cell-python</code></a>
<ul>
<li><a href="#install-wire-cell-python">5.1.1. Installing <code>wire-cell-python</code></a></li>
<li><a href="#python-programs">5.1.2. Python command line programs</a></li>
<li><a href="#python-modules">5.1.3. <code>wirecell</code> Python modules</a></li>
</ul>
</li>
<li><a href="#pkg-util">5.2. <code>wire-cell-util</code></a>
<ul>
<li><a href="#util-units">5.2.1. Units</a></li>
<li><a href="#util-persistence">5.2.2. Persistence</a></li>
<li><a href="#org7cc8787">5.2.3. Etc</a></li>
</ul>
</li>
<li><a href="#pkg-iface">5.3. <code>wire-cell-iface</code></a>
<ul>
<li><a href="#orgb52a592">5.3.1. Data</a></li>
<li><a href="#orgbefe70d">5.3.2. Nodes</a></li>
<li><a href="#org098fc46">5.3.3. Misc</a></li>
</ul>
</li>
<li><a href="#pkg-gen">5.4. <code>wire-cell-gen</code></a>
<ul>
<li><a href="#orgffb04f8">5.4.1. Depositions</a></li>
<li><a href="#org558677d">5.4.2. Drifting</a></li>
<li><a href="#org000ab8b">5.4.3. Response</a></li>
<li><a href="#org79049ff">5.4.4. Digitizing</a></li>
<li><a href="#orgee481a8">5.4.5. Noise</a></li>
<li><a href="#org06c8675">5.4.6. Frame Summing</a></li>
<li><a href="#org03b33d2">5.4.7. Execution Graphs</a></li>
</ul>
</li>
<li><a href="#pkg-waftools">5.5. <code>wire-cell-waftools</code></a>
<ul>
<li><a href="#generate-wcb">5.5.1. Recreating <code>wcb</code></a></li>
<li><a href="#bundle-waf-tools">5.5.2. Included Waf tools</a></li>
<li><a href="#main-wscript">5.5.3. The main <code>wscript</code></a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#data-flow-programming">6. Data Flow Programming</a>
<ul>
<li><a href="#orgba50abb">6.1. Node basics</a></li>
<li><a href="#org3ebede2">6.2. Node execution paradigms</a></li>
<li><a href="#org57fb9f6">6.3. DFP execution strategies</a></li>
<li><a href="#orge6914f2">6.4. End-of-stream Protocol</a></li>
</ul>
</li>
<li><a href="#other-topics">7. Other Topics</a>
<ul>
<li><a href="#garfield-2d-support">7.1. Garfield 2D Support</a>
<ul>
<li><a href="#garfield-2d-data">7.1.1. Garfield 2D data</a></li>
<li><a href="#preprocessing-garfield-data">7.1.2. Preprocessing of Garfield 2D data</a></li>
<li><a href="#eyeball-garfield">7.1.3. Eyeballing Garfield 2D with <code>wirecell.sigproc.garfield</code></a></li>
<li><a href="#garfield-validation-plots">7.1.4. Validation plots</a></li>
<li><a href="#convert-garfield-data-to-json">7.1.5. Producing WCT Field Response Data File</a></li>
</ul>
</li>
<li><a href="#larsoft-integration">7.2. Running inside of art/LArSoft</a>
<ul>
<li><a href="#wcls-overview">7.2.1. Overview</a></li>
<li><a href="#wcls-design">7.2.2. Design</a></li>
<li><a href="#wcls-config">7.2.3. Configuration</a></li>
<li><a href="#wcls-run">7.2.4. Runtime</a></li>
<li><a href="#wcls-dev">7.2.5. Development</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div id="outline-container-orga9059cf" class="outline-2">
<h2 id="installation"><a id="user-content-installation" class="anchor" href="#installation" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-2">1</span> Installation</h2>
<div class="outline-text-2" id="text-installation">
<p>
The Wire Cell Toolkit (WCT) should be easy to build on any POSIX’y system with a recent C++ compiler. This section describes how to build releases and development branches, it gives guidance for supplying the few software dependencies, and documents how releases are made.
</p>
</div>
<div id="outline-container-org458c5f4" class="outline-3">
<h3 id="toolkit-installation"><a id="user-content-toolkit-installation" class="anchor" href="#toolkit-installation" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-3">1.1</span> Toolkit installation</h3>
<div class="outline-text-3" id="text-toolkit-installation">
<div class="warning">
<p>
This assumes you already have available the required dependencies. See section <a href="#installing-dependencies">1.3</a>.
</p>
</div>
<p>
Installation requires four steps:
</p>
<ol class="org-ol">
<li>get the source</li>
<li>configure the source</li>
<li>build the code</li>
<li>install the results</li>
</ol>
</div>
<div id="outline-container-org37671cd" class="outline-4">
<h4 id="source-code"><a id="user-content-source-code" class="anchor" href="#source-code" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.1.1</span> Source code</h4>
<div class="outline-text-4" id="text-source-code">
<p>
WCT source is composed of several packages (see section <a href="#packages">5</a>) and all source is available from the <a href="https://github.com/WireCell/">Wire Cell GitHub organization</a>. Releases of each package are made and documented on GitHub (<i>eg</i> <a href="https://github.com/WireCell/wire-cell-toolkit/releases">here</a>) 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.
</p>
<p>
To obtain a release requires no GitHub authentication:
</p>
<pre class="example">
$ git clone --branch 0.5.x \
https://github.com/WireCell/wire-cell-toolkit.git
</pre>
<p>
This gets the tip of a release branch (the <code>0.5.x</code> series in this example).
A specific point release can then be checked out:
</p>
<pre class="example">
$ git checkout -b 0.5.0 0.5.0
</pre>
<p>
To contribute new development to the toolkit, even as a “core”
developer, it’s recommended to <i>fork</i> the <code>wire-cell-toolkit</code> 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.
</p>
<p>
Core developers can nonetheless directly push to the central
repository. It’s suggested to do so via an SSH authenticated clone:
</p>
<pre class="example">
$ git clone [email protected]:WireCell/wire-cell-toolkit.git wct
</pre>
</div>
</div>
<div id="outline-container-orgec14f1c" class="outline-4">
<h4 id="configuring-the-source"><a id="user-content-configuring-the-source" class="anchor" href="#configuring-the-source" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.1.2</span> Configuring the source</h4>
<div class="outline-text-4" id="text-configuring-the-source">
<p>
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 <a href="./waftools.html">./waftools.html</a>.
</p>
<p>
On systems where software dependencies can be auto-detected, the
configuration step may be as simple as:
</p>
<pre class="example">
$ ./wcb configure \
--prefix=/path/to/install
</pre>
<p>
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.
</p>
<p>
Dependencies may be automatically located if <code>pkg-config</code> is available and possibly by suitably setting the <code>PKG_CONFIG_PATH</code> 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 <code>WCT_EXTERNALS</code> environment variable (not, this variable has no other special meaning other than to make this example brief).
</p>
<pre class="example">
$ ./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
</pre>
<p>
If the externals are not all in one directory then their locations must be accordingly specified individually.
</p>
</div>
</div>
<div id="outline-container-org7d3bc0f" class="outline-4">
<h4 id="building-the-source"><a id="user-content-building-the-source" class="anchor" href="#building-the-source" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.1.3</span> Building the source</h4>
<div class="outline-text-4" id="text-building-the-source">
<p>
It is suggested to first build the code before running tests.
</p>
<pre class="example">
$ ./wcb -p --notests
</pre>
<p>
If there are build failures more information can be obtained by repeating the build with more verbosity:
</p>
<pre class="example">
$ ./wcb -vv
</pre>
</div>
</div>
<div id="outline-container-org04edaaf" class="outline-4">
<h4 id="install-built-code"><a id="user-content-install-built-code" class="anchor" href="#install-built-code" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.1.4</span> Install the results</h4>
<div class="outline-text-4" id="text-install-built-code">
<p>
To install the build results into the location given by <code>--prefix</code> simply issue:
</p>
<pre class="example">
$ ./wcb install --notests
</pre>
</div>
</div>
<div id="outline-container-org2dda46a" class="outline-4">
<h4 id="running-unit-tests"><a id="user-content-running-unit-tests" class="anchor" href="#running-unit-tests" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.1.5</span> Running unit tests</h4>
<div class="outline-text-4" id="text-running-unit-tests">
<div class="note">
<p>
Unit tests are meant to be small, focused tests. More elaborate tests may be found in the <a href="https://github.com/wirecell/wire-cell-validate">wire-cell-validate</a> package.
</p>
</div>
<p>
Tests are run by default by <code>./wcb</code> unless <code>--notests</code> 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:
</p>
<pre class="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)
</pre>
<div class="INFO">
<p>
Developers wishing to run unit tests that exercise code they are developing should take care in setting <code>LD_LIBRARY_PATH</code>. If the WCT installation area is included then the unit tests will run against those libraries, effectively masking the locally built versions in the development area. Alternatively, they must run <code>./wcb install</code> and then manually re-run the unit test.
</p>
</div>
</div>
</div>
<div id="outline-container-org687ba50" class="outline-4">
<h4 id="other-build-commands"><a id="user-content-other-build-commands" class="anchor" href="#other-build-commands" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.1.6</span> Other build commands</h4>
<div class="outline-text-4" id="text-other-build-commands">
<p>
These other commands may be useful:
</p>
<pre class="example">
$ ./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.
</pre>
</div>
</div>
</div>
<div id="outline-container-orgf8928c3" class="outline-3">
<h3 id="runtime-environment"><a id="user-content-runtime-environment" class="anchor" href="#runtime-environment" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-3">1.2</span> Runtime environment</h3>
<div class="outline-text-3" id="text-runtime-environment">
<p>
Managing environment is usually a personal choice or computer facility policy and WCT does not place any significant requirements on this. The usual setting of <code>PATH</code> like variables will likely be needed.
</p>
<p>
Internally, WCT requires a minimum of environment variables:
</p>
<dl class="org-dl">
<dt><code>WIRECELL_PATH</code></dt><dd>a list of directories to search when locating configuration files. More information is in the section <a href="#configuration">2</a>.</dd>
</dl>
</div>
</div>
<div id="outline-container-org9dc35fd" class="outline-3">
<h3 id="installing-dependencies"><a id="user-content-installing-dependencies" class="anchor" href="#installing-dependencies" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-3">1.3</span> Guide for installation of dependencies</h3>
<div class="outline-text-3" id="text-installing-dependencies">
<p>
The WCT depends on a number of third-party “external” software packages which are not expected to be provided by a typical unix-like system:
</p>
<dl class="org-dl">
<dt>Boost</dt><dd>various functions</dd>
<dt>Eigen3</dt><dd>matrix representation, interface to FFTW</dd>
<dt>FFTW3</dt><dd>for fast Fast Fourier Transforms</dd>
<dt>JsonCPP</dt><dd>basis for configuration and input data files</dd>
<dt>Jsonnet</dt><dd>structured configuration files.</dd>
</dl>
<p>
Additional, optional package are needed for additional functionality:
</p>
<dl class="org-dl">
<dt>ROOT</dt><dd>for the <code>root/</code> sub-package, not required for core code</dd>
<dt>TBB</dt><dd>for parallel, multi-threaded data flow programming paradigm support</dd>
<dt>CUDA</dt><dd>support for some GPU technologies</dd>
</dl>
<div class="note">
<p>
This list may not represent current reality.
To get a full, up-to-date list of what packages WCT can use run <code>./wcb --help</code>.
</p>
</div>
<p>
The following subsections gives some guidance for obtaining these “external” packages.
</p>
</div>
<div id="outline-container-orgc280e64" class="outline-4">
<h4 id="manual-externals-install"><a id="user-content-manual-externals-install" class="anchor" href="#manual-externals-install" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.3.1</span> Manual Installation of Externals</h4>
<div class="outline-text-4" id="text-manual-externals-install">
<p>
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.
</p>
<p>
However the installer decides to build in DIY-mode the WCT build system should be able to be given proper installation locations via the <code>--with-*</code> flags as described above. If it seems not to be the case, please contact the developers.
</p>
</div>
</div>
<div id="outline-container-orgcb7b5aa" class="outline-4">
<h4 id="singularity-cvmfs-externals"><a id="user-content-singularity-cvmfs-externals" class="anchor" href="#singularity-cvmfs-externals" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.3.2</span> Singularity containers and CVMFS</h4>
<div class="outline-text-4" id="text-singularity-cvmfs-externals">
<p>
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 <a href="https://github.com/WireCell/wire-cell-singularity">wire-cell-singularity</a> package.
</p>
</div>
</div>
<div id="outline-container-orgb9a4cd6" class="outline-4">
<h4 id="spack-installed-externals"><a id="user-content-spack-installed-externals" class="anchor" href="#spack-installed-externals" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.3.3</span> Automated Installation with Spack</h4>
<div class="outline-text-4" id="text-spack-installed-externals">
<p>
<a href="https://github.com/LLNL/spack">Spack</a> 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 <a href="http://modules.sourceforge.net/">Environment Modules</a> to handle your users’ setup of these packages or can make targeted release “views” of its package tree.
</p>
<p>
WCT provides a package <a href="https://github.com/WireCell/wire-cell-spack">wire-cell-spack</a> 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.
</p>
<p>
An installer that wishes to use wire-cell-spack to provide the dependencies should begin by following its <a href="https://github.com/WireCell/wire-cell-spack/blob/master/README.org">README</a> file.
</p>
</div>
</div>
<div id="outline-container-org01a8306" class="outline-4">
<h4 id="using-externals-from-ups"><a id="user-content-using-externals-from-ups" class="anchor" href="#using-externals-from-ups" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.3.4</span> Externals provided by UPS</h4>
<div class="outline-text-4" id="text-using-externals-from-ups">
<p>
Fermi National Accelerator Lab (FNAL) uses a user environment system similar to <a href="http://modules.sourceforge.net/">Environment Modules</a>. It is typical to download binaries provided by FNAL, either manually of automatically via a CVMFS mount, and then use the UPS shell function <code>setup</code> 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 <code>--with-*</code> flags to <code>wcb</code> as described above. The source provides a script <code>waftools/wct-configure-for-ups.sh</code> which may help run <code>./wcb configure</code> in such an environment.
</p>
</div>
</div>
</div>
<div id="outline-container-org84a529a" class="outline-3">
<h3 id="release-management"><a id="user-content-release-management" class="anchor" href="#release-management" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-3">1.4</span> Release management</h3>
<div class="outline-text-3" id="text-release-management">
<p>
Releases are made by developers as needed and as described in this section.
</p>
</div>
<div id="outline-container-orgbd88a81" class="outline-4">
<h4 id="release-versions"><a id="user-content-release-versions" class="anchor" href="#release-versions" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.4.1</span> Release versions</h4>
<div class="outline-text-4" id="text-release-versions">
<p>
WCT label releases are made following a fixed procedure. Releases are labeled with the common three-number convention: <code>X.Y.Z</code>. These take the following semantic meanings:
</p>
<dl class="org-dl">
<dt>X</dt><dd>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.</dd>
<dt>Y</dt><dd>a minor or feature release is made when substantial new and in particular any breaking development is made.</dd>
<dt>Z</dt><dd>a bug release fixes problems without otherwise substantial changes.</dd>
</dl>
</div>
</div>
<div id="outline-container-org16353c1" class="outline-4">
<h4 id="branch-policy"><a id="user-content-branch-policy" class="anchor" href="#branch-policy" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.4.2</span> Branch policy</h4>
<div class="outline-text-4" id="text-branch-policy">
<p>
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 <code>master</code>. Nominally, all development is on the <code>master</code> 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.
</p>
</div>
</div>
<div id="outline-container-org22510c9" class="outline-4">
<h4 id="branch-mechanics"><a id="user-content-branch-mechanics" class="anchor" href="#branch-mechanics" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">1.4.3</span> Branch mechanics</h4>
<div class="outline-text-4" id="text-branch-mechanics">
<p>
To make releases, the above details are baked into two test scripts <a href="https://github.com/WireCell/waf-tools/blob/master/make-release.sh">make-release.sh</a> and <a href="https://github.com/WireCell/waf-tools/blob/master/test-release.sh">test-release.sh</a>. 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.
</p>
</div>
</div>
</div>
</div>
<div id="outline-container-org4389adb" class="outline-2">
<h2 id="configuration"><a id="user-content-configuration" class="anchor" href="#configuration" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-2">2</span> Configuration</h2>
<div class="outline-text-2" id="text-configuration">
<p>
As the Wire Cell Toolkit (WCT) is a toolkit, it is up to the parent application to provide some mechanism for the user to provide configuration information to WCT <i>components</i>. Users should refer to the application’s documentation for details. This section of the manual documents the configuration mechanism that is provided by WCT itself. If an application decides to use the WCT file format then its users may refer to this document. Developers of WCT components should read it as well.
</p>
</div>
<div id="outline-container-orgbb2c6e8" class="outline-3">
<h3 id="configuration-introduction"><a id="user-content-configuration-introduction" class="anchor" href="#configuration-introduction" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-3">2.1</span> Introduction</h3>
<div class="outline-text-3" id="text-configuration-introduction">
<p>
WCT itself provides a mechanism which is exposed to the user by the <code>wire-cell</code> command line application. Any application may easily adopt this same mechanism by making use of the <code>WireCell::ConfigManager</code> class.
</p>
<p>
This WCT configuration mechanism is described here from the point of view of <b>user</b> and <b>developer</b>. Details for each role are given in the following sections. However, both user and developer must understand one aspect of WCT internal design in order to understand configuration: A WCT application is composed of a number of <i>component</i> classes. Components work together in some way to enact the job of the application. A component is specifically a C++ class which implements one or more <i>interface</i> base classes. One interface pertinent here is <code>IConfigurable</code>. A component that implements this interface is called a <i>configurable component</i> or just <i>configurable</i>. A configurable then is the atomic unit of WCT configuration and this unit is reflected in what the user provides for configuration and what developers should expect if they write configurable components.
</p>
<p>
The user then provides an ordered sequence of <i>configuration objects</i> or simply <i>configurations</i>. Each configuration is associated (by WCT) with exactly one <i>instance</i> of a configurable component class. This association is done via two string identifiers:
</p>
<dl class="org-dl">
<dt>type</dt><dd>specifies the “configurable type” which often matches the C++ class name with any C++ namespace removed. However, developers of configurable components are free to chose any unique type name.</dd>
<dt>name</dt><dd>specifies a “configurable instance”, that is an C++ object instance of the C++ class associated with the configurable type identifier. The name is free form and may be omitted in which case it defaults to the empty string. A specific name is needed if multiple instances are required or if multiple configurables require sharing a component.</dd>
</dl>
<div class="note">
<p>
A type/name pair is are also used to initially construct and later locate any instance of a WCT component (not just configurable components).
</p>
</div>
<p>
Finally, configurations have a third attribute:
</p>
<dl class="org-dl">
<dt>data</dt><dd>specifies a data structure following a schema specific to the configurable type. This is the “payload” that WCT gives to the instance of the configurable component.</dd>
</dl>
<p>
In the next section, WCT user-configuration support is described. After it, the following section gives guidance to developers who wish to write their own configurable components.
</p>
</div>
</div>
<div id="outline-container-org4758aeb" class="outline-3">
<h3 id="user-configuration"><a id="user-content-user-configuration" class="anchor" href="#user-configuration" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-3">2.2</span> Configuration from a user point of view   <span class="tag"><span class="user">user</span></span></h3>
<div class="outline-text-3" id="text-user-configuration">
<p>
Users of the WCT command line interface <code>wire-cell</code> (or any WCT application that uses <code>WireCell::ConfigManager</code>) can provide configuration information in the form of one or more files. These files express the ordered configuration sequence that is conceptually described above.
</p>
</div>
<div id="outline-container-orgd2d133b" class="outline-4">
<h4 id="configuration-file-formats"><a id="user-content-configuration-file-formats" class="anchor" href="#configuration-file-formats" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">2.2.1</span> File formats</h4>
<div class="outline-text-4" id="text-configuration-file-formats">
<p>
WCT supports two related configuration file formats: <a href="http://www.json.org/">JSON</a> and <a href="http://jsonnet.org/">Jsonnet</a>. 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.
</p>
</div>
</div>
<div id="outline-container-org4d60b2f" class="outline-4">
<h4 id="configuration-command-line"><a id="user-content-configuration-command-line" class="anchor" href="#configuration-command-line" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">2.2.2</span> Basic command line</h4>
<div class="outline-text-4" id="text-configuration-command-line">
<p>
A user gives one or more configuration files to the <code>wire-cell</code> application each with a <code>-c</code> flag:
</p>
<pre class="example">
$ wire-cell -c myparameters.cfg [...]
</pre>
<p>
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 <code>WIRECELL_PATH</code> 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.
</p>
</div>
</div>
<div id="outline-container-org8357b1a" class="outline-4">
<h4 id="diving-into-json"><a id="user-content-diving-into-json" class="anchor" href="#diving-into-json" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">2.2.3</span> Diving into JSON</h4>
<div class="outline-text-4" id="text-diving-into-json">
<p>
An example JSON configuration for a single component might look like:
</p>
<div class="org-src-container">
<pre class="src src-js">[
{
<span style="font-style: italic;">"data"</span> : {
<span style="font-style: italic;">"clight"</span> : 1,
<span style="font-style: italic;">"step_size"</span> : 0.10000000000000001,
<span style="font-style: italic;">"tracks"</span> : []
},
<span style="font-style: italic;">"name"</span> : <span style="font-style: italic;">""</span>,
<span style="font-style: italic;">"type"</span> : <span style="font-style: italic;">"TrackDepos"</span>
}
]
</pre>
</div>
<p>
Here we see an array holding one element which is an object with the <code>type</code>, (instance) <code>name</code> and payload data= structure as described above. If <code>wire-cell</code> were to load this configuration it would create a default instance of the component type <code>TrackDepos</code> which happens to correspond to the C++ class <code>WireCell::Gen::TrackDepos</code> (see the <a href="./gen.html">simulation package manual</a> for more information). This component is responsible for produces deposition (<code>IDepo</code>) objects using a simple linear source model.
</p>
<p>
The <code>tracks</code> 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 <code>tracks</code> array. WCT support bzip2 compressed JSON files (see the section on <a href="./util.html#util-persistence">persistence in the util package manual</a>).
</p>
</div>
</div>
<div id="outline-container-org272386b" class="outline-4">
<h4 id="json-limitations"><a id="user-content-json-limitations" class="anchor" href="#json-limitations" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">2.2.4</span> Limitations of JSON</h4>
<div class="outline-text-4" id="text-json-limitations">
<p>
As the complexity of a <code>wire-cell</code> job grows, hand crafting JSON becomes tedious and error prone. Splitting the files and/or using <code>WIRECELL_PATH</code> can provide some rudimentary means of organizing a large, complex configuration.
</p>
<p>
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 <code>TrackDepos</code> configuration as a long <code>tracks</code> array.
</p>
<p>
Another limitation is that any numerical quantities <b>must</b> be expressed in the base units used by the WCT <i>system of units</i> (see the section on <a href="./util.html#util-units">units in the Utilities manual</a>). This places a burden on the configuration author and is a source of error.
</p>
<p>
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.
</p>
</div>
</div>
<div id="outline-container-orgb95a2c5" class="outline-4">
<h4 id="learning-jsonnet"><a id="user-content-learning-jsonnet" class="anchor" href="#learning-jsonnet" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-4">2.2.5</span> Learning Jsonnet</h4>
<div class="outline-text-4" id="text-learning-jsonnet">
<p>
WCT provides support for configuration files following the <a href="http://jsonnet.org/">Jsonnet data templating language</a>. This language is evaluated to produce JSON. WCT can evaluation Jsonnet files directly. The user may also install the <code>jsonnet</code> command line program which is useful for validating Jsonnet files. Either the valid Jsonnet or the JSON it produces may be given to WCT.
</p>
<p>
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 <a href="https://github.com/wirecell/wire-cell-cfg">wire-cell-cfg</a> 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 <a href="https://github.com/WireCell/wire-cell-cfg/blob/master/wirecell.jsonnet">wirecell.jsonnet</a>. Some of this exported functionality is illustrated below.
</p>
<p>
WCT locates Jsonnet files as it does JSON files through the environment variable <code>WIRECELL_PATH</code>. Unlike JSON files, Jsonnet files may not be compressed.
</p>
</div>
<div id="outline-container-org53d7479" class="outline-5">
<h5 id="system-of-units-in-jsonnet"><a id="user-content-system-of-units-in-jsonnet" class="anchor" href="#system-of-units-in-jsonnet" aria-hidden="true"><svg aria-hidden="true" class="octicon octicon-link" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><span class="section-number-5">2.2.5.1</span> System of units</h5>
<div class="outline-text-5" id="text-system-of-units-in-jsonnet">
<p>
Wire Cell provides an internal system of units as described in the section on <a href="./util.html#util-units">units in the Utilities manual</a> and as stated above, users must take care to give numerical quantities in WCT units when providing JSON. However, when writing Jsonnet one can provide explicit units which is easy and far less error prone. For example:
</p>
<div class="org-src-container">
<pre class="src src-js">local wc = <span style="font-weight: bold;">import</span> <span style="font-style: italic;">"wirecell.jsonnet"</span>;
[
{
type:<span style="font-style: italic;">"TrackDepos"</span>,