% Created 2021-08-31 Tue 11:13
% Intended LaTeX compiler: pdflatex
\documentclass[presentation]{beamer}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{grffile}
\usepackage{longtable}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{textcomp}
\usepackage{amssymb}
\usepackage{capt-of}
\usepackage{hyperref}
\usepackage[outputdir=latexmk-out]{minted}
\usepackage{pdfpages}
\usepackage{xcolor}
\usepackage{graphicx}
\usepackage{xspace}
\usepackage{libertine}
\usepackage{fontawesome}
\mode<beamer>{\usetheme{Boadilla}}
\setbeamertemplate{navigation symbols}{}
\hypersetup{colorlinks}
\setbeamerfont{alerted text}{series=\bfseries}
\usemintedstyle{emacs}
\usetheme{default}
\author{Brett Viren}
\date{\today}
\title{Wire-Cell Toolkit Architecture}
\subtitle{The Basics}
\hypersetup{
 pdfauthor={Brett Viren},
 pdftitle={Wire-Cell Toolkit Architecture},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={Emacs 27.2 (Org mode 9.4.6)}, 
 pdflang={English}}
\begin{document}

\maketitle

\begin{frame}[label={sec:org6f769aa}]{Wire-Cell Basic Topics}
\begin{itemize}
\item Getting started
\item Interface classes
\item Components
\item Data flow graph
\item Applications
\item Packaging
\item Plugins
\item Logging
\item Util
\item Configuration
\item Documentation and community
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org37b7c96}]{Introduction}
The Wire-Cell Toolkit (WCT) provides

\footnotesize

\begin{itemize}
\item A general purpose \alert{component architecture} including an \alert{execution framework}.
\item \alert{Implementations} solving various \alert{LAr TPC} problems.
\item \alert{Configuration system} with examples for most major LAr TPC detectors.
\item \alert{Support data files} (detector description, response function, noise spectra).
\item A \alert{command line application}.
\item Modular \alert{Python support} package and command line interfaces.
\item Extensible \alert{build system} for the toolkit and \alert{user packages}.
\item Documentation, and community (GitHub, blog, Mattermost, mailing list)
\end{itemize}
\end{frame}


\begin{frame}[label={sec:orgf691698},fragile]{Architectural layers of entry to the Wire-Cell Toolkit}
 \footnotesize

\begin{description}
\item[{interfaces}] the toolkit API, well-factored abstract base class hierarchy.

\item[{components}] a unit of functionality, implements a number of \emph{interfaces}.

\item[{aggregation}] combine concrete components or via their interfaces
to produce arbitrary execution patterns.

\item[{named factory}] dynamically produce an \emph{interface} given the \emph{type
and instance} names of its concrete component from \emph{runtime plugins}.

\item[{data flow}] aggregate \texttt{INode} \emph{interfaces} into a \emph{data flow graph} to be
executed by one of the provided \emph{engines}, also implemented as a \emph{component}.

\item[{configuration}] the \texttt{IConfigurable} interface can be fed by the
application or by WCT's simple and flexible configuration language.

\item[{apps}] high-level behavior bundled into WCT ``app'' components.

\item[{main}] top-level (application as a tool) behavior with \texttt{Main} class.

\item[{embed}] other applications may call into any of these layers.

\item[{user interface}] toolkit provides the \texttt{wire-cell} command line
interface.
\end{description}
\end{frame}


\begin{frame}[label={sec:orgab402a1},fragile]{Interface classes}
 An \alert{abstract base class} defines one or more
\alert{pure-virtual methods} and describes the \alert{expected behavior} of the implementation.

\begin{block}{}
\begin{minted}[]{c++}
class IMethod {
  public:
    // Do something, return result or -1 on error.
    virtual int method(double val) = 0;
};
\end{minted}
\end{block}
\end{frame}


\begin{frame}[label={sec:orgaf93be7},fragile]{WCT Interface Library}
 All ``official'' WCT interfaces are in a single WCT sub-package:

\begin{description}
\item[{source}] \texttt{wire-cell-toolkit/iface/}
\item[{header}] \texttt{\#include "WireCellIface/IMyInterface.h"}
\item[{library}] \texttt{libWireCellIface.so}
\end{description}
\end{frame}


\begin{frame}[label={sec:org98ca14e},fragile]{WCT Interface Class Hierarchy (roots)}
 \begin{columns}
\begin{column}{0.5\columnwidth}
\includegraphics[width=\textwidth]{interfaces.pdf}
\end{column}

\begin{column}{0.5\columnwidth}
\scriptsize 
Two branches in the interface class hierarchy:

\begin{itemize}
\item \emph{nouns} : all \alert{data interfaces} are from \texttt{IData<TYPE>}
\item \emph{verbs} : all \alert{component interfaces} are from \texttt{IComponent<TYPE>}
\end{itemize}

The \href{https://en.wikipedia.org/wiki/Curiously\_recurring\_template\_pattern}{CRTP} is used to provide some standard types:

\begin{description}
\item[{\texttt{pointer}}] a \texttt{shared\_ptr} to the interface
\item[{\texttt{vector}}] a vector of \texttt{pointer}
\end{description}

All interfaces are held by \texttt{shared\_ptr<>}.
\end{column}
\end{columns}
\end{frame}

\begin{frame}[label={sec:org56d574d},fragile]{Some WCT \texttt{IData} interfaces}
 \begin{description}
\item[{\texttt{IDepo}}] a localized distribution of ionization electrons.
\item[{\texttt{IWire}}] represent information about one wire segment
\item[{\texttt{IChannel}}] an electronics channel to which wires feed
\item[{\texttt{IFrame}}] dense or spare representation of waveforms.
\item[{\texttt{ISlice}}] a slice in time of a frame.
\item[{\texttt{IBLob}}] a voxel in space with associated value (eg, charge)
\item[{\texttt{ICluster}}] a set of associations between blobs
\item[{\texttt{ITensor}}] a general, dense array of some shape
\end{description}

Some collections of \texttt{IData}, themselves \texttt{IData} are also defined.
\end{frame}

\begin{frame}[label={sec:orge3b61c7}]{Components - WCT's verbs}
\begin{itemize}
\item A \alert{component interface} defines methods that ``do'' something.
\item A \alert{concrete component} (or briefly, just ``\alert{component}'') is an
implementation of one or more component interfaces.
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org9f8345e},fragile]{WCT component categories}
 \begin{description}
\item[{nodes}] an \texttt{INode} provides a function-like object that may serve as a vertex in a WCT \emph{data flow graph}.
\begin{itemize}
\item \scriptsize Similar to Gaudi Algorithm or \emph{art} Module though the different node types span a variety of interfaces.
\end{itemize}
\item[{services}] an API to some information or process.
\begin{itemize}
\item \scriptsize Similar to service or tools from Gaudi or \emph{art} though less constrained.
\end{itemize}
\item[{features}] provide some kind of feature to the component
\begin{itemize}
\item \emph{eg}: naming, configuring, finalizing.
\end{itemize}
\end{description}

A component is usually a \alert{node} or a \alert{service} and not both typically
provide one ore more \alert{feature} component interfaces.
\end{frame}

\begin{frame}[label={sec:org67f5ab4},fragile]{Concrete component inherits from interfaces}
 \begin{block}{}
\scriptsize
\begin{minted}[]{c++}
class MyFilter : public virtual IFrameFilter,
                 public virtual IConfigurable {
  public:
    // IFrameFilter
    virtual bool operator()(const input_pointer& inframe,
                            output_pointer& outframe);
    // IConfigurable
    virtual void configure(const WireCell::Configuration& config);
    virtual WireCell::Configuration default_configuration() const;
}
\end{minted}
\end{block}


\begin{block}{}
\tiny
\begin{minted}[]{c++}
// Sketch of the interface class hierarchy

class IFunctionNodeBase : public INode  { ... }

template <typename InputType, typename OutputType>
class IFunctionNode : public IFunctionNodeBase  { ... }

class IFrameFilter : public virtual IFunctionNode<IFrame,IFrame>  { ... }

class IConfigurable : virtual public IComponent<IConfigurable> { ... }
\end{minted}
\end{block}
\end{frame}



\begin{frame}[label={sec:orgcbd7ad8},fragile]{Component factory registration}
 \begin{block}{In \texttt{src/MyFilter.cxx}}
\scriptsize

\begin{minted}[]{c++}

#include "WireCellUtil/NamedFactory.h"
WIRECELL_FACTORY(MyFilter, WireCell::MyNS::MyFilter,
                 WireCell::IFrameFilter,
                 WireCell::IConfigurable)
\end{minted}
\end{block}

\begin{block}{}
\scriptsize

Factory uses a ``type name'' (\texttt{MyFilter} here) which is technically distinct from but
typically chosen to be identical to the component's C++ class name.
\end{block}
\end{frame}


\begin{frame}[label={sec:org92612e2},fragile]{Method implementation}
 \begin{block}{The node execution operator}
\footnotesize

\begin{minted}[]{c++}
bool MyFilter::operator()(const input_pointer& in,
                          output_pointer& out)
{
    out = nullptr;
    if (!in) { return true; }   // more on EOS later
    out = apply_filter(in);
    return true;
}
// configuration related methods described later.
\end{minted}
\end{block}

\begin{block}{}
Returning \texttt{false} is for source nodes to signal they are exhausted.
\end{block}
\end{frame}

\begin{frame}[label={sec:org751e95a},fragile]{Use Named Factory to produce interface instances}
 \begin{block}{Produce instances of interfaces}
\scriptsize

\begin{minted}[]{c++}
// One component instance, two interface instances
auto si = Factory::lookup<ISomeInterface>("MyType", "a-name");
auto oi = Factory::find<IOtherInterface>("MyType", "a-name");
si->some_method();
oi->other_method();

// Additional instances of different "type" or "instance" names.
auto si2 = Factory::find<ISomeInterface>("MyType", "another-name");
auto si3 = Factory::find<ISomeInterface>("YourType", "a-name");

\end{minted}
\end{block}

\begin{block}{}
\scriptsize
The production of an instance of an interface is parameterized by:
\begin{itemize}
\item C++ interface type,
\item The component ``type name'' and
\item An optional component ``instance name''.
\end{itemize}
\end{block}

\begin{block}{}
\scriptsize

\texttt{INode+IConfigurable} components will typically retrieve and hold \emph{service} type components from in
their \texttt{configure()} method.  \texttt{IAnodePlane} is a common one to need.
\end{block}
\end{frame}

\begin{frame}[label={sec:orgceba46e},fragile]{WCT dataflow graph}
 WCT can execute \texttt{INode} components aggregated into a \href{https://en.wikipedia.org/wiki/Dataflow\_programming}{dataflow programming} (DFP) graph.

\footnotesize
\begin{itemize}
\item A \alert{node} may consume or produce data through its \alert{ports}.
\item A \alert{port} shall pass data of a given type.
\item An \alert{edge} transfers data of fixed type from one \alert{output port} to one \alert{input port}.
\item A node is in one \alert{category} based on its pattern of ports and behavior.
\begin{itemize}
\item \scriptsize some categories: source, sink, function, fanin, fanout
\end{itemize}
\item Dataflow ``programming'' means to construct a graph.
\begin{itemize}
\item \scriptsize WCT provides dynamic graph construction driven by configuration.
\item Port type and occupancy rules are asserted during construction.
\end{itemize}
\item A valid DFP graph may then be \alert{executed} by an \alert{engine}.
\begin{itemize}
\item \scriptsize WCT supplies two engines.
\end{itemize}
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org5ba0e97},fragile]{Simple DFP graph}
 \begin{center}
\includegraphics[width=0.7\textwidth]{graph-two-nodes.pdf}
\end{center}

\begin{itemize}
\item Graph engine executes source node \texttt{FrameFileSource:0}.
\item Source produces \texttt{IFrame} on its output port 0 and exits.
\item Engine transfers \texttt{IFrame} on edge and executes the succeeding node.
\item \texttt{DumpFrames:0} inputs \texttt{IFrame} on port 0, does some logging, exits.
\item Engine continues until sources are exhausted and edges are drained.
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org337eaa2},fragile]{WCT DFP Stream Protocol}
 A \alert{stream} is the \emph{sequence of data} seen on an \alert{edge} between two \alert{node
ports}.  The stream is terminated by a special \alert{end-of-stream} (EOS)
marker.

\scriptsize

\begin{verbatim}
stream: ([data(0)], ..., [data(i)], ..., [data(n-1)], [EOS])
\end{verbatim}

\normalsize

\begin{itemize}
\item Analogous to a C-string of characters terminated with \texttt{'\textbackslash{}0'}.
\begin{itemize}
\item Each ``character'' is a \texttt{std::shared\_ptr<TYPE>}
\item \texttt{[data(i)]} holds a non-NULL pointer, \texttt{[EOS]} holds \texttt{nullptr}.
\end{itemize}
\item A node should flush out any cached data when an EOS is input.
\item A node with EOS input shall output a corresponding EOS.
\item A new stream may follow an EOS.
\end{itemize}

\footnotesize When a source is \emph{fully exhausted} of streams, it's next
execution after the final EOS shall return \texttt{false}.  The engine should
then not execute the source node again and the graph will begin to
drain.  Graph execution then terminates.
\end{frame}




\begin{frame}[label={sec:org28304cb},fragile]{Larger example: sim, sigproc, 3D imaging, file I/O}
 \begin{center}
\includegraphics[width=\textwidth]{graph-simspimg.pdf}
\end{center}

\footnotesize
\begin{itemize}
\item \texttt{IDepoSet} data is read from file, drifted and 6-way \emph{fanned} out.
\item Per-APA pipelines implement simulation, signal processing and 3D imaging.
\item Intermediate 2-way fanout forwards \texttt{IFrame} down pipeline and to
\texttt{FrameFileSink}, one each for ``\texttt{orig}'' and ``\texttt{gauss}'' frames.
\item Each pipeline is capped to save the final \texttt{ICluster}.
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org3fb2c9b},fragile]{WCT has two graph execution engines}
 \texttt{Pgrapher}
\begin{itemize}
\item Single threaded, executes only one node at any time.
\item Available in core WCT with no extra dependencies.
\item Executes graph in reverse topological order, minimizes memory usage.
\item Some graphs suffer a speed pathology for \(\mathcal{O}(10^5)\) \texttt{IData} or more.
\end{itemize}

\texttt{TbbFlow}
\begin{itemize}
\item Multi-threaded, execute nodes in parallel.
\item Requires WCT built with TBB.
\item Parallelism limited by a given max number of threads.
\item Efficient even with 1 \(\mu\)s node execution times.
\item Allows multiple data ``in flight'' at once, higher total memory usage.
\end{itemize}

Both are identical in terms of their configuration and use.
\end{frame}


\begin{frame}[label={sec:org1880d03},fragile]{WCT applications vs WCT apps}
 Confusingly, there are two similar terms meaning totally different things:

\footnotesize
\begin{description}
\item[{``application''}] WCT can be embedded in some ``external'' application.
\begin{itemize}
\item \scriptsize WCT provides the \texttt{wire-cell} command line program as a
simple example of embedding \texttt{Main} into a ``Wire-Cell Toolkit
application''.
\item The \texttt{larwirecell} package (part of LArSoft) provides an \emph{art} ``tool''
called \texttt{WCLS\_tool} that calls \texttt{WireCell::Main} and an \emph{art} ``module''
that can operate the ``tool''.  The package also provides WCT
components that know how to handle LArSoft data.
\end{itemize}
\item[{``app''}] WCT ``internally'' defines an ``app'' (confusingly as an
\texttt{IApplication} interface) to represent any kind of high-level
execution.
\begin{itemize}
\item \scriptsize the \texttt{Main} class can execute zero or more ``apps''.
\item \texttt{Pgrapher} and \texttt{TbbFlow} have been introduced.
\item Others include the little used \texttt{ConfigDumper} and \texttt{NodeDumper}.
\end{itemize}
\end{description}
\end{frame}

\begin{frame}[label={sec:orgf1a0a62},fragile]{Package dependency hierarchy}
 \begin{center}
\includegraphics[width=\textwidth]{wct-deps.pdf}
\end{center}

\footnotesize

\begin{description}
\item[{Non-WCT}] external dependencies
\item[{\texttt{WireCellUtil}}] low-level utility code used by all WCT.
\item[{\texttt{WireCellIface}}] all ``official'' interfaces.
\item[{\texttt{WireCellAux}}] mid-level utility based on interfaces.
\item[{\texttt{WireCell*}}] (all the rest) Wire-Cell Toolkit plugin libraries.
\end{description}

Graph is made based on local build config (eg, \texttt{WireCellRoot} not shown).

Gray lines are dependency through the unit tests (not libraries).
\end{frame}

\begin{frame}[label={sec:orgf1ee3f4}]{Tour of select WCT sub-packages}
\begin{center}
\begin{tabular}{lll}
c & WireCellGen & TPC noise and signal simulation.\\
c & WireCellSigProc & TPC noise filtering and signal processing.\\
c & WireCellImg & TPC 3D imaging.\\
c & WireCellPgraph & single-thread data flow graph execution.\\
 & WireCellTbb & multi-thread data flow graph execution.\\
c & WireCellSio & ``simple'' I/O, Numpy, tar, JSON.\\
 & WireCellHio & HDF5 based I/O.\\
 & WireCellPytorch & DNNROI TPC signal processing.\\
 & WireCellZio & experimental ZeroMQ services.\\
 & WireCellRoot & ROOT I/O and ROOT-based unit tests.\\
\end{tabular}
\end{center}

\footnotesize
\begin{itemize}
\item Roughly categorized by ``topic'' and/or by a major, optional dependency.
\item Those marked ``c'' are considered in the ``core WCT'', not requiring optional dependencies.
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org14acd5e},fragile]{Wire-Cell Toolkit packages}
 Name:

\footnotesize
\begin{itemize}
\item \texttt{wire-cell-toolkit/<name>/} for an ``official'' WCT package
\item \texttt{any-thing-you-want/} for any WCT ``user'' package in separate repo
\end{itemize}

\normalsize
Layout under \texttt{/<name>/}:

\footnotesize
\begin{itemize}
\item \texttt{src/*.cxx} holds library source and private header files.
\item \texttt{inc/} holds public library headers under \texttt{WireCell<Name>/*.h}
\item \texttt{test/test\_*.cxx} unit test programs.
\begin{itemize}
\item \scriptsize Also: \texttt{test*.sh}, \texttt{test*.py}, \texttt{test*.jsonnet}.
\end{itemize}
\item \texttt{apps/<program>.cxx} source for \texttt{program} providing \texttt{main()} (rare).
\item \texttt{wscript\_build} brief package build info.  Example:
\end{itemize}

\begin{verbatim}
$ cat gen/wscript_build 
bld.smplpkg('WireCellGen', use='WireCellAux')
\end{verbatim}
\end{frame}

\begin{frame}[label={sec:orge0d7b2e},fragile]{Wire-Cell Toolkit ``user'' packages (WCUP)}
 A WCUP is simply a WCT-like sub-directory in its own repo.

\begin{itemize}
\item Possible to add to \texttt{wire-cell-toolkit} proper at some later time.
\item No WCT library shall depend on a WCUP library
\item A WCUP library shall only depend on WCT via \texttt{WireCellAux} and
\texttt{WireCellIface} libraries.
\end{itemize}

Examples of WCUPs:

\scriptsize
\begin{itemize}
\item \url{https://github.com/brettviren/pcbro}
\item \url{https://github.com/wirecell/wire-cell-gen-kokkos}
\end{itemize}

\normalsize 
The \texttt{moo} program has a WCUP skeleton generator.

\scriptsize
\begin{itemize}
\item \url{https://brettviren.github.io/moo/wcup.html}
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org2c1454f},fragile]{WCT plugins}
 A WCT plugin is any shared library containing WCT components.

\vfill

For automated loading, WCT must be told about all plugin libraries by
name either via configuration or the command line:

\begin{verbatim}
$ wire-cell -p MyPlugin [...]
\end{verbatim}


Plugin names: \texttt{MyPlugin} is provided by \texttt{libMyPlugin.so}.
\end{frame}


\begin{frame}[label={sec:orgc6bde16},fragile]{Logging in WCT components}
 \footnotesize

\begin{minted}[]{c++}
// MyComponent.h
#include "WireCellAux/Logger.h"
class MyComponent : public WireCell::Aux::Logger, ... {
    // ...
    size_t m_count{0};
    double m_var{0};
}

// MyComponent.cxx
MyComponent::MyComponent()
  : WireCell::Aux::Logger("MyComponent", "pkg") { ... }

void MyComponent::some_method() {
    // ...
    log->debug("call={} var={}", m_count, m_var);
 }  
\end{minted}

We give the \alert{type name} used by named factory and a \alert{logging group} 
name (usually the short package name: ``gen'', ``sigproc'', ``img'', etc).
\end{frame}


\begin{frame}[label={sec:org07a0da9},fragile]{Tracing}
 Very verbose logging can use CPU even if its log is not emitted.

Embed very noisy log generation in a CPP macro that can be disabled at
compile-time.

\vfill

\scriptsize
\begin{minted}[]{c++}
// from img/src/BlobClustering.cxx
SPDLOG_LOGGER_TRACE(log, "got {} blobs, holding graph with {}",
                    blobset->blobs().size(),
                    boost::num_vertices(m_grind.graph()));
\end{minted}

Of course, do not put side-effects inside this macro!

\vfill
\end{frame}

\begin{frame}[label={sec:org8d02e07},fragile]{Log level guidelines}
 WCT uses \texttt{spdlog} which has ``sinks'' with ranked ``levels''.

In order of desired decreasing verbosity:

\begin{description}
\item[{trace}] more than one call per ``event'' for any given component.
\item[{debug}] O(1) call per ``event'' from any given component.
\item[{info}] O(1) call from entire job run, communicate some end-result to the user (likely rare to actually use).
\item[{warn}] a rare, non-fatal problem related to some specific input.
\item[{error}] emit just prior to handling some rare but expected error.
\item[{critical}] emit just prior to throwing exception or returning due
to an error that was not handled locally.
\end{description}

\footnotesize
\begin{itemize}
\item If a component works at smaller scale than ``event'', be mindful not to over-emit \alert{debug} and prefer \alert{trace}.
\item Consider using a dedicated logging \alert{group} for such overly noisy components.
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org0e826a4},fragile]{Control over logging}
 CLI via the \texttt{Main} class controls log sinks and their levels
\begin{itemize}
\item \footnotesize By default, all logging is \alert{off}.  User must do something to see logs!
\end{itemize}


Define a sink to standard out and a lowest level of ``debug'':

\begin{verbatim}
$ wire-cell -l stdout -L debug [...]
\end{verbatim}

Define a file sink with special level ``trace''

\begin{verbatim}
$ wire-cell \
   -l noisy.log:trace -l error.log:error \
   -L trace [...]
\end{verbatim}
\end{frame}


\begin{frame}[label={sec:orgdbb2695},fragile]{\texttt{WireCellUtil} - the base package}
 Low level utility code that plugins will directly compile against

\begin{itemize}
\item Base \texttt{Interface} and \texttt{IComponent} and \texttt{NamedFactory}.
\item Arrays, waveforms, FFT, binning, bounding box.
\item Graphs, sets, 3D vectors, coordinate transforms, system of units.
\item Ray grid, tiling, solving support for 3D img.
\item Exceptions, persistency, configuration, base objects.
\end{itemize}
\end{frame}

\begin{frame}[label={sec:orgf0f94b5},fragile]{WCT System of Units in C++}
 In WCT \alert{every} numeric literal \alert{must} be given a unit.

\footnotesize
\begin{minted}[]{c++}
#include "WireCellUtil/Units.h"
const double drift_speed = 1.6 * (units::mm/units::ms);

log->("Drift speed is {} parsecs per picoseconds",
      drift_speed / (units::parsec/units::picosecond));
\end{minted}

\begin{itemize}
\item Always \alert{multiple} a unit to a literal to bring the value, or a value
just read in from some external source, into the system of units.
\item Always \alert{divide} by a unit to express in explicit units.
\end{itemize}

\scriptsize

``Never'' use values in any other system of units but if you must, mark the variable with the unit:

\begin{minted}[]{c++}
const double tick = 0.5*units::us;
const double tick_ns = tick / units::ns;
log->debug("the tick is {}ns", tick_ns);
\end{minted}
\end{frame}


\begin{frame}[label={sec:org3729f31},fragile]{WCT configuration subsystem}
 \begin{itemize}
\item Configuration is given in form of a JSON-like (JsonCPP) object\footnote{There are plans to transition to \texttt{nlohmann::json}.}.

\item \texttt{ConfigManager} can parse configuration files and feed results to \texttt{IConfigurable} instances.
\begin{itemize}
\item Normally users need not worry about this, \texttt{Main} handles it.
\end{itemize}

\item WCT directly supports reading files in Jsonnet or JSON format.
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org88ca530},fragile]{Component configuration}
 \footnotesize
\begin{minted}[]{c++}
using namespace WireCell;

// Tell toolkit our default configuration.
Configuration MyFilter::default_configuration() const {
    Configuration cfg;
    cfg["threshold"] = m_threshold;
    return cfg;
}
// Recieve actual configuration from toolkit.
void MyFilter::configure(const Configuration& cfg) {
    m_threshold = get(cfg, "threshold", m_threshold);
}
\end{minted}

Note: this is expected to change soon to provide schema control and
type safety and reduce boilerplate code.
\end{frame}


\begin{frame}[label={sec:org89ac6dc},fragile]{The configuration sequence}
 WCT is configured with an dependency-ordered array of config objects:

\begin{verbatim}
config sequence: [ [cfgobj], ..., [cfgobj] ]
\end{verbatim}

Each config object has a standard trio of top-level keys:

\footnotesize

\begin{verbatim}
{
    type: "MyFilter",
    name: "a-name",
    data: {
        threshold: 1.0,
        offset: 100*wc.us,  // more on units in config later
    }
}
\end{verbatim}

\begin{description}
\item[{type}] the ``type name'' registered with named factory.
\item[{name}] an optional ``instance name'' for named factory lookup.
\item[{data}] the configuration expected by the component type.
\end{description}
\end{frame}

\begin{frame}[label={sec:org7d79631},fragile]{Constructing configuration with Jsonnet}
 This can be a talk all by itself
\begin{itemize}
\item Read Jsonnet's very fine \href{https://jsonnet.org/learning/tutorial.html}{tutorial}, \href{https://jsonnet.org/ref/stdlib.html}{stdlib} and \href{https://jsonnet.org/ref/language.html}{reference} documentation.
\end{itemize}

WCT-specific provides Jsonnet support files:

\begin{itemize}
\item \texttt{wirecell.jsonnet} for units, low-level utility functions.
\item \texttt{pgraph.jsonnet} help constructing DFP graph configurations.
\item \texttt{vector.jsonnet} vector arithmetic.
\item \texttt{pgrapher/experiment/*} detector-specific configuration.
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org375988b},fragile]{Feeding configuration}
 Set \texttt{WIRECELL\_PATH} to include \texttt{wire-cell-toolkit/cfg/} or set include on
command line as:

\begin{verbatim}
$ wire-cell [ ... ] \
            -P /path/to/wire-cell-toolkit/cfg \
            -c my-main-config.jsonnet
\end{verbatim}

\footnotesize

An application may use \texttt{Main} for easy feeding of config to WCT

\begin{itemize}
\item \scriptsize In \emph{art} / LArSoft, the \texttt{WCLS\_tool} provides a FHiCL \(\to\) WCT config path.
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org14ec2e5},fragile]{WCT System of Units in configuration}
 Same rules apply as with C++: \alert{always} give units to numeric literals.

\vfill

\begin{verbatim}
local wc = import "wirecell.jsonnet";
local mycfg = {
    drift_speed: 1.6 * (wc.mm/wc.us);
};
\end{verbatim}

\vfill
\end{frame}



\begin{frame}[label={sec:org8cf220e},fragile]{Configuration ``bulk'' data files}
 Large, generated config required by some WCT components.

\begin{itemize}
\item They are typically generated by dedicated, external programs.
\begin{itemize}
\item Some of which may be found in \texttt{wire-cell-python}.
\end{itemize}
\item Generation takes too much time to run ``live'' in a WCT job.
\end{itemize}

These files are provided in the \texttt{wire-cell-data} package:

\begin{itemize}
\item Description of \alert{wire geometry} for popular detectors and
\item Their pre-calcualted \alert{field responses}.
\item Models of \alert{noise spectra} for the simulation.
\end{itemize}

\vfill

\footnotesize

Also include directory in \texttt{WIRECELL\_PATH} or with \texttt{wire-cell -P [....]}.

\vfill
\end{frame}

\begin{frame}[label={sec:orga9de968}]{Documentation and community}
\footnotesize

Main doc page
\begin{itemize}
\item \url{https://wirecell.github.io/}
\end{itemize}
Manual
\begin{itemize}
\item \url{https://wirecell.github.io/manual.html}
\end{itemize}
Tutorial
\begin{itemize}
\item \url{https://czczc.github.io/wire-cell-tutorial/}
\end{itemize}
News ``blog'':
\begin{itemize}
\item \url{https://wirecell.github.io/news/}
\end{itemize}
Doxygen reference
\begin{itemize}
\item \url{https://wirecell.github.io/doxy/html/}
\end{itemize}
Mattermost (chat)
\begin{itemize}
\item \url{https://chat.sdcc.bnl.gov/edg/channels/wire-cell}
\end{itemize}
\end{frame}


\begin{frame}[label={sec:org0e28c5f}]{}
\begin{center}
\Huge \(\mathcal{FIN}\)
\end{center}
\end{frame}

\begin{frame}[label={sec:org3acccad}]{}
\begin{center}
\emph{backups}
\end{center}
\end{frame}


\begin{frame}[label={sec:org5cbd8c0},fragile]{Getting source}
 \footnotesize

Released archives:

\url{https://github.com/WireCell/wire-cell-toolkit/releases}

\vfill

Or users may use \texttt{git}:

\begin{verbatim}
$ git clone https://github.com/WireCell/wire-cell-toolkit.git
\end{verbatim}

\vfill

Developers should use:
\begin{verbatim}
$ git clone git@github.com:WireCell/wire-cell-toolkit.git
\end{verbatim}
\end{frame}

\begin{frame}[label={sec:org522a212}]{Dependencies}
\begin{columns}
\begin{column}{0.3\columnwidth}
Required

\begin{itemize}
\item Boost
\item TBB
\item Eigen3
\item FFTW
\item Jsonnet
\item JsonCPP
\item spdlog
\end{itemize}
\end{column}

\begin{column}{0.4\columnwidth}
Optional

\begin{itemize}
\item TBB (recommended)
\item HDF5 and H5CPP
\item ROOT
\item CUDA, Kokkos, Torch
\item ZeroMQ and related
\end{itemize}
\end{column}
\end{columns}

\begin{block}{}
\scriptsize

Providing dependencies is the job of the user.  Not described here,
but various Docker/Singularity images, Fermilab/UPS products, Spack
recipes, etc are available.  Most of the dependencies are provided by
a reasonable OS such as Debian.
\end{block}
\end{frame}

\begin{frame}[label={sec:orga8d937a},fragile]{Installation}
 \begin{block}{Build and install}
\begin{verbatim}
$ cd wire-cell-toolkit/
$ ./wcb --help
$ ./wcb configure --prefix=/path/to/install [...]
$ ./wcb install --notests
\end{verbatim}
\end{block}

\begin{block}{}
\footnotesize

Various \texttt{-{}-with-*} options can be given to help \texttt{wcb} find dependencies.
\end{block}

\begin{block}{}
\footnotesize

Now add \texttt{/path/to/install/\{bin,lib\}} directories to your various \texttt{PATH} vars.
\end{block}
\end{frame}

\begin{frame}[label={sec:org3176c2b},fragile]{Test the build}
 \begin{block}{Command line interfaces}
\begin{verbatim}
$ wire-cell --help
$ wire-cell --version
$ wcsonnet --help
\end{verbatim}
\end{block}

\begin{block}{Unit tests}
\begin{verbatim}
$ ./wcb --alltests
\end{verbatim}
\end{block}
\end{frame}


\begin{frame}[label={sec:orgb9406cd}]{Why interfaces?}
\begin{itemize}
\item High-level composition while hiding low-level detail.
\begin{itemize}
\item \scriptsize ``I don't care what your class does as long as it follows the interface.''
\end{itemize}

\item Low-level implementation ignoring high-level structure.
\begin{itemize}
\item \scriptsize ``I don't care how you use my class, I will focus on satisfying the interface.''
\end{itemize}

\item Dynamic and in particular, configuration-driven composition.
\begin{itemize}
\item \scriptsize ``We must mix and match the same code in different ways and do not want to write more C++ each time we want something new.''
\end{itemize}

\item Plugin architecture support.
\begin{itemize}
\item \scriptsize ``Simply name my library to use my components, no need to recompile.''
\end{itemize}
\end{itemize}
\end{frame}



\begin{frame}[label={sec:orgf2ec4c6},fragile]{Data as an interface}
 \begin{itemize}
\item Somewhat unique (aka ``controversial'') compared to other systems.
\item Separate usage from data origin and physical representation.
\begin{itemize}
\item Most algorithms should not care about file formats.
\item Transient/persistent fully decoupled.
\item ``Smart'' data\footnote{WCT exploited this by providing a lazy-loading \texttt{IFrame}
data type.  This ``saved the day'' by fighting otherwise ruinous memory
usage due to ROOT overhead and the ProtoDUNE-SP \emph{art} / LArSoft ``raw
digit'' data model that is input to WCT signal processing.} or simple ``bags of values''.
\end{itemize}
\item No specific need for an ``event store'' (\emph{eg} as in Gaudi or \emph{art}).
\begin{itemize}
\item \footnotesize \texttt{IData} interfaces may be implemented with an ``event store'' backend.
\end{itemize}
\end{itemize}
\end{frame}
\end{document}
