% Created 2025-05-30 Fri 15:00
% Intended LaTeX compiler: pdflatex
\documentclass[usenames,dvipsnames,colorlinks,aspectratio=169]{beamer}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{capt-of}
\usepackage{hyperref}
\usepackage{color}
\usepackage{listings}
\usepackage{pdfpages}
\usepackage{xcolor}
\usepackage{graphicx}
\usepackage{xspace}
\usepackage{siunitx}
\usepackage{libertine}
\usepackage{fontawesome}
\mode<beamer>{\usetheme{Boadilla}}
\setbeamertemplate{navigation symbols}{}
\setbeamerfont{alerted text}{series=\bfseries}
\setbeamercolor{alerted text}{fg=blue}
\usecolortheme{default}
\usefonttheme{serif}
\usefonttheme{professionalfonts}
\lstloadlanguages{[ISO]C++}
\definecolor{codegreen}{rgb}{0,0.6,0}
\definecolor{codegray}{rgb}{0.5,0.5,0.5}
\definecolor{codepurple}{rgb}{0.50,0,0.82}
\definecolor{codeorange}{rgb}{0.95,0.3,0.1}
\definecolor{backcolour}{rgb}{0.95,0.95,0.92}
\lstdefinestyle{mystyle}{
commentstyle=\color{codegreen},
keywordstyle=\color{codeorange},
numberstyle=\tiny\color{codegray},
stringstyle=\color{codepurple},
basicstyle=\footnotesize,
breakatwhitespace=false,
breaklines=true,
captionpos=b,
keepspaces=true,
numbers=left,
numbersep=5pt,
showspaces=false,
showstringspaces=false,
showtabs=false,
tabsize=2
}
\lstset{style=mystyle}
\usetheme{default}
\author{Brett Viren}
\date{\today}
\title{\(2^{nd}\) round of \texttt{clus/} cleanups}
\subtitle{A focus on graphs}
\hypersetup{
 pdfauthor={Brett Viren},
 pdftitle={\(2^{nd}\) round of \texttt{clus/} cleanups},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={Emacs 28.2 (Org mode 9.8-pre)},
 pdflang={English}}

% Setup for code blocks [1/2]

\usepackage{fvextra}

\fvset{%
  commandchars=\\\{\},
  highlightcolor=white!95!black!80!blue,
  breaklines=true,
  breaksymbol=\color{white!60!black}\tiny\ensuremath{\hookrightarrow}}

% Make line numbers smaller and grey.
\renewcommand\theFancyVerbLine{\footnotesize\color{black!40!white}\arabic{FancyVerbLine}}

\usepackage{xcolor}

% In case engrave-faces-latex-gen-preamble has not been run.
\providecolor{EfD}{HTML}{f7f7f7}
\providecolor{EFD}{HTML}{28292e}

% Define a Code environment to prettily wrap the fontified code.
\usepackage[breakable,xparse]{tcolorbox}
\DeclareTColorBox[]{Code}{o}%
{colback=EfD!98!EFD, colframe=EfD!95!EFD,
  fontupper=\footnotesize\setlength{\fboxsep}{0pt},
  colupper=EFD,
  IfNoValueTF={#1}%
  {boxsep=2pt, arc=2.5pt, outer arc=2.5pt,
    boxrule=0.5pt, left=2pt}%
  {boxsep=2.5pt, arc=0pt, outer arc=0pt,
    boxrule=0pt, leftrule=1.5pt, left=0.5pt},
  right=2pt, top=1pt, bottom=0.5pt,
  breakable}

% Support listings with captions
\usepackage{float}
\floatstyle{plain}
\newfloat{listing}{htbp}{lst}
\newcommand{\listingsname}{Listing}
\floatname{listing}{\listingsname}
\newcommand{\listoflistingsname}{List of Listings}
\providecommand{\listoflistings}{\listof{listing}{\listoflistingsname}}


% Setup for code blocks [2/2]: syntax highlighting colors

\newcommand\efstrut{\vrule height 2.1ex depth 0.8ex width 0pt}
\definecolor{EFD}{HTML}{000000}
\definecolor{EfD}{HTML}{ffffff}
\newcommand{\EFD}[1]{\textcolor{EFD}{#1}} % default
\definecolor{EFvp}{HTML}{000000}
\newcommand{\EFvp}[1]{\textcolor{EFvp}{#1}} % variable-pitch
\definecolor{EFh}{HTML}{7f7f7f}
\newcommand{\EFh}[1]{\textcolor{EFh}{#1}} % shadow
\definecolor{EFsc}{HTML}{228b22}
\newcommand{\EFsc}[1]{\textcolor{EFsc}{\textbf{#1}}} % success
\definecolor{EFw}{HTML}{ff8e00}
\newcommand{\EFw}[1]{\textcolor{EFw}{\textbf{#1}}} % warning
\definecolor{EFe}{HTML}{ff0000}
\newcommand{\EFe}[1]{\textcolor{EFe}{\textbf{#1}}} % error
\definecolor{EFl}{HTML}{ff0000}
\newcommand{\EFl}[1]{\textcolor{EFl}{#1}} % link
\definecolor{EFlv}{HTML}{ff0000}
\newcommand{\EFlv}[1]{\textcolor{EFlv}{#1}} % link-visited
\definecolor{EFhi}{HTML}{ff0000}
\newcommand{\EFhi}[1]{\textcolor{EFhi}{#1}} % highlight
\definecolor{EFc}{HTML}{b22222}
\newcommand{\EFc}[1]{\textcolor{EFc}{#1}} % font-lock-comment-face
\definecolor{EFcd}{HTML}{b22222}
\newcommand{\EFcd}[1]{\textcolor{EFcd}{#1}} % font-lock-comment-delimiter-face
\definecolor{EFs}{HTML}{8b2252}
\newcommand{\EFs}[1]{\textcolor{EFs}{#1}} % font-lock-string-face
\definecolor{EFd}{HTML}{8b2252}
\newcommand{\EFd}[1]{\textcolor{EFd}{#1}} % font-lock-doc-face
\definecolor{EFm}{HTML}{008b8b}
\newcommand{\EFm}[1]{\textcolor{EFm}{#1}} % font-lock-doc-markup-face
\definecolor{EFk}{HTML}{9370db}
\newcommand{\EFk}[1]{\textcolor{EFk}{#1}} % font-lock-keyword-face
\definecolor{EFb}{HTML}{483d8b}
\newcommand{\EFb}[1]{\textcolor{EFb}{#1}} % font-lock-builtin-face
\definecolor{EFf}{HTML}{0000ff}
\newcommand{\EFf}[1]{\textcolor{EFf}{#1}} % font-lock-function-name-face
\definecolor{EFv}{HTML}{a0522d}
\newcommand{\EFv}[1]{\textcolor{EFv}{#1}} % font-lock-variable-name-face
\definecolor{EFt}{HTML}{228b22}
\newcommand{\EFt}[1]{\textcolor{EFt}{#1}} % font-lock-type-face
\definecolor{EFo}{HTML}{008b8b}
\newcommand{\EFo}[1]{\textcolor{EFo}{#1}} % font-lock-constant-face
\definecolor{EFwr}{HTML}{ff0000}
\newcommand{\EFwr}[1]{\textcolor{EFwr}{\textbf{#1}}} % font-lock-warning-face
\newcommand{\EFnc}[1]{#1} % font-lock-negation-char-face
\definecolor{EFpp}{HTML}{483d8b}
\newcommand{\EFpp}[1]{\textcolor{EFpp}{#1}} % font-lock-preprocessor-face
\newcommand{\EFrc}[1]{\textbf{#1}} % font-lock-regexp-grouping-construct
\newcommand{\EFrb}[1]{\textbf{#1}} % font-lock-regexp-grouping-backslash
\newcommand{\EFob}[1]{#1} % org-block
\newcommand{\EFobb}[1]{#1} % org-block-begin-line
\newcommand{\EFobe}[1]{#1} % org-block-end-line
\definecolor{EFOa}{HTML}{0000ff}
\newcommand{\EFOa}[1]{\textcolor{EFOa}{#1}} % outline-1
\definecolor{EFOb}{HTML}{a0522d}
\newcommand{\EFOb}[1]{\textcolor{EFOb}{#1}} % outline-2
\definecolor{EFOc}{HTML}{a020f0}
\newcommand{\EFOc}[1]{\textcolor{EFOc}{#1}} % outline-3
\definecolor{EFOd}{HTML}{b22222}
\newcommand{\EFOd}[1]{\textcolor{EFOd}{#1}} % outline-4
\definecolor{EFOe}{HTML}{228b22}
\newcommand{\EFOe}[1]{\textcolor{EFOe}{#1}} % outline-5
\definecolor{EFOf}{HTML}{008b8b}
\newcommand{\EFOf}[1]{\textcolor{EFOf}{#1}} % outline-6
\definecolor{EFOg}{HTML}{483d8b}
\newcommand{\EFOg}[1]{\textcolor{EFOg}{#1}} % outline-7
\definecolor{EFOh}{HTML}{8b2252}
\newcommand{\EFOh}[1]{\textcolor{EFOh}{#1}} % outline-8
\definecolor{EFhn}{HTML}{008b8b}
\newcommand{\EFhn}[1]{\textcolor{EFhn}{#1}} % highlight-numbers-number
\definecolor{EFhq}{HTML}{9370db}
\newcommand{\EFhq}[1]{\textcolor{EFhq}{#1}} % highlight-quoted-quote
\definecolor{EFhs}{HTML}{008b8b}
\newcommand{\EFhs}[1]{\textcolor{EFhs}{#1}} % highlight-quoted-symbol
\definecolor{EFrda}{HTML}{707183}
\newcommand{\EFrda}[1]{\textcolor{EFrda}{#1}} % rainbow-delimiters-depth-1-face
\definecolor{EFrdb}{HTML}{7388d6}
\newcommand{\EFrdb}[1]{\textcolor{EFrdb}{#1}} % rainbow-delimiters-depth-2-face
\definecolor{EFrdc}{HTML}{909183}
\newcommand{\EFrdc}[1]{\textcolor{EFrdc}{#1}} % rainbow-delimiters-depth-3-face
\definecolor{EFrdd}{HTML}{709870}
\newcommand{\EFrdd}[1]{\textcolor{EFrdd}{#1}} % rainbow-delimiters-depth-4-face
\definecolor{EFrde}{HTML}{907373}
\newcommand{\EFrde}[1]{\textcolor{EFrde}{#1}} % rainbow-delimiters-depth-5-face
\definecolor{EFrdf}{HTML}{6276ba}
\newcommand{\EFrdf}[1]{\textcolor{EFrdf}{#1}} % rainbow-delimiters-depth-6-face
\definecolor{EFrdg}{HTML}{858580}
\newcommand{\EFrdg}[1]{\textcolor{EFrdg}{#1}} % rainbow-delimiters-depth-7-face
\definecolor{EFrdh}{HTML}{80a880}
\newcommand{\EFrdh}[1]{\textcolor{EFrdh}{#1}} % rainbow-delimiters-depth-8-face
\definecolor{EFrdi}{HTML}{887070}
\newcommand{\EFrdi}[1]{\textcolor{EFrdi}{#1}} % rainbow-delimiters-depth-9-face
\definecolor{EFany}{HTML}{CDCD00}
\newcommand{\EFany}[1]{\textcolor{EFany}{#1}} % ansi-color-yellow
\definecolor{EFanr}{HTML}{CD0000}
\newcommand{\EFanr}[1]{\textcolor{EFanr}{#1}} % ansi-color-red
\definecolor{EFanb}{HTML}{000000}
\newcommand{\EFanb}[1]{\textcolor{EFanb}{#1}} % ansi-color-black
\definecolor{EFang}{HTML}{00CD00}
\newcommand{\EFang}[1]{\textcolor{EFang}{#1}} % ansi-color-green
\definecolor{EFanB}{HTML}{0000EE}
\newcommand{\EFanB}[1]{\textcolor{EFanB}{#1}} % ansi-color-blue
\definecolor{EFanc}{HTML}{00CDCD}
\newcommand{\EFanc}[1]{\textcolor{EFanc}{#1}} % ansi-color-cyan
\definecolor{EFanw}{HTML}{E5E5E5}
\newcommand{\EFanw}[1]{\textcolor{EFanw}{#1}} % ansi-color-white
\definecolor{EFanm}{HTML}{CD00CD}
\newcommand{\EFanm}[1]{\textcolor{EFanm}{#1}} % ansi-color-magenta
\definecolor{EFANy}{HTML}{EEEE00}
\newcommand{\EFANy}[1]{\textcolor{EFANy}{#1}} % ansi-color-bright-yellow
\definecolor{EFANr}{HTML}{EE0000}
\newcommand{\EFANr}[1]{\textcolor{EFANr}{#1}} % ansi-color-bright-red
\newcommand{\EFANb}[1]{#1} % ansi-color-bright-black
\definecolor{EFANg}{HTML}{00EE00}
\newcommand{\EFANg}[1]{\textcolor{EFANg}{#1}} % ansi-color-bright-green
\definecolor{EFANB}{HTML}{0000FF}
\newcommand{\EFANB}[1]{\textcolor{EFANB}{#1}} % ansi-color-bright-blue
\definecolor{EFANc}{HTML}{00EEEE}
\newcommand{\EFANc}[1]{\textcolor{EFANc}{#1}} % ansi-color-bright-cyan
\newcommand{\EFANw}[1]{#1} % ansi-color-bright-white
\newcommand{\EFANm}[1]{#1} % ansi-color-bright-magenta
\begin{document}

\maketitle
\begin{frame}[label={sec:org89f918d},fragile]{Overview}
 \begin{itemize}
\item Relevant Issues on GitHub.

\item Introduction of new facade: \texttt{Ensemble}.

\item Introduction of new concept: cluster flags.

\item Transferring of cluster state.

\item Cluster IDs

\item Bee issues and wire-cell-python improvements

\item Cluster cache issues

\item New support for graphs and graph algorithms

\item Factoring ``clustering retile'' to prep for patrec

\item Comments on issues that are still open.
\end{itemize}
\end{frame}
\begin{frame}[label={sec:org7d646fc},fragile,shrink=10]{Relevant issues on github}
 \begin{block}{\texttt{wire-cell-toolkit}}
\begin{itemize}
\item\relax [8/11] Cluster graph and other prep for future porting efforts. \href{https://github.com/WireCell/wire-cell-toolkit/issues/414}{\#414}
\begin{itemize}
\item[{$\boxtimes$}] Multi-grouping API for Cluster and MABC \#416
\item[{$\boxtimes$}] Multi-graph storage on Cluster facade \#419
\item[{$\boxtimes$}] Clustering Dijkstra's shortest path refactoring \#417
\item[{$\boxtimes$}] Refactor Cluster::examine\textsubscript{graph}() \#418
\item[{$\boxtimes$}] Factor body of ClusteringRetile main loop into a stand-alone function \#415
\item[{$\boxtimes$}] Normalize the enumeration of cluster IDs \#421
\item[{$\boxtimes$}] Small blobs can have no ``stepped'' sample points. \#425
\item[{$\boxtimes$}] WCT allows duplicate component instance type/names which violates the rules. \#427
\item[{$\square$}] \texttt{Cluster} facade has grown state not related to caching and it needs control \#420
\item[{$\square$}] Stand-alone PCA is needed for \texttt{clus} \#423
\item[{$\square$}] Copy-pasted \texttt{Cluster} state transfer code needs to be replaced with \texttt{Cluster::from()} \#424
\end{itemize}
\end{itemize}
\end{block}
\begin{block}{Tangential}
\begin{itemize}
\item[{$\square$}] \texttt{HaiwangYu/wcp-porting-img} \href{https://github.com/HaiwangYu/wcp-porting-img/issues/7}{Ambigously named BlobSampler live/dead pairs in ``pdhd'' test.}
\item[{$\square$}] BlobSampler API has become broken which lays a trap for the user. \#426
\end{itemize}
\end{block}
\begin{block}{Comments on open issues at end.}
\end{block}
\end{frame}
\begin{frame}[label={sec:org5760039},fragile,shrink=10]{\texttt{Ensemble} PC tree node facade and \texttt{IEnsembleVistor}}
 \begin{Code}
\begin{Verbatim}
\color{EFD}\EFcd{//} \EFc{old}
\EFt{void} \EFo{IClusteringMethod}::\EFf{clustering}(\EFt{Grouping}\& \EFv{a}, \EFt{Grouping}\& \EFv{b}, \EFt{cluster\_set\_t}\& \EFv{c});

\EFcd{//} \EFc{new}
\EFt{void} \EFo{IEnsembleVisitor}::\EFf{visit}(\EFo{Facade}::\EFt{Ensemble}\& \EFv{ensemble}) \EFk{const};
\end{Verbatim}
\end{Code}

\begin{itemize}
\item New, generalized name and API.
\begin{itemize}
\item Use for both ``clustering'' and ``pattern recognition''.
\end{itemize}
\item The \texttt{cluster\_set\_t\& c} replaced with ``cluster flags'' (described next).
\item \texttt{Ensemble} is a \alert{new facade} to a \alert{new PC tree root node}
\begin{itemize}
\item Children nodes carry \texttt{Grouping} facades.
\item Gives access to child \texttt{Grouping} by \alert{name}.
\end{itemize}
\item Visitors may create new \texttt{Grouping} (eg ``shadow'') without nuking others (eg ``dead'').
\end{itemize}
\begin{block}{MABC support changes}
\begin{itemize}
\item \texttt{Ensemble} is merely a \alert{temporary} used inside MABC.
\item Load input based on \texttt{Grouping} name list (default: \texttt{["live", "dead"]}).
\item Output saves a ``loose'' set of \texttt{Grouping} to \texttt{ITensorSet} to retain past behavior.
\item In/out ``datapaths'' may be configured on per-grouping basis with reasonable defaults.
\end{itemize}
\end{block}
\end{frame}
\begin{frame}[label={sec:org48d6678},fragile,shrink=10]{Introduce new concept: ``cluster flags''}
 \begin{block}{Currently just one usage to mark ``the cluster is connected to a dead cluster''}
\begin{Code}
\begin{Verbatim}
\color{EFD}\EFcd{//} \EFc{clustering\_live\_dead.cxx sets it initially.}
cluster->set\_flag(\EFo{Flags}::live\_dead);
\EFcd{//} \EFc{merge\_clusters() transfers it, via from() (more on this later).}
fresh\_cluster.from(*old\_cluster);
\EFcd{//} \EFc{clustering\_extend() tests it.}
\EFk{if} (cluster->get\_flag(\EFo{Flags}::live\_dead)) \{ ... \}
\end{Verbatim}
\end{Code}
\end{block}
\begin{block}{Ways to use cluster flags}
\begin{itemize}
\item Define a subset of clusters that hold a common flag.
\begin{itemize}
\item Replace the special-purpose "\texttt{cluster\_set\_t"} with \texttt{Flags::live\_dead}.
\end{itemize}
\item Flags are actually \texttt{int} so can take value in addition to indicating a yes/no.
\end{itemize}
\end{block}
\begin{block}{Inventing new flags}
New flags are defined by adding a \texttt{const string} variable in \texttt{namespace Flags} eg in
\texttt{ClusteringFuncs.h}.  Don't use literal strings in code.
\end{block}
\end{frame}
\begin{frame}[label={sec:org984addb},fragile]{New \texttt{Cluster::from(const Cluster\&)} method}
 \texttt{Cluster} has gained ``state'' beyond mere cache (it is not really a ``facade'' any
more).  Worse, user should not care but now is forced to manage this state.  At
the least, we should minimize this management burden.  Instead of copy-paste
many lines, user must now call \texttt{from()} to transfer the extra state.

\begin{Code}
\begin{Verbatim}
\color{EFD}\EFcd{//} \EFc{Now, just one line:}
fresh\_cluster.from(*old\_cluster);

\EFcd{//} \EFc{Defined as}
\EFt{void} \EFo{Cluster}::\EFf{from}(\EFk{const} \EFt{Cluster}\& \EFv{other})
\{
    \EFk{this}->default\_scope\_from(other);
    \EFk{this}->flags\_from(other);
\}
\end{Verbatim}
\end{Code}
Do \alert{not} extend this.  See \href{https://github.com/WireCell/wire-cell-toolkit/issues/424}{\#424} for some todos.
\end{frame}
\begin{frame}[label={sec:orgb445d42},fragile]{Cluster ident}
 \begin{itemize}
\item All the facades provide methods: \texttt{int ident()/set\_ident(int)}
\begin{itemize}
\item Do not make up special methods to do the same thing.
\end{itemize}
\item Cluster ID numbering:
\begin{itemize}
\item Past: clusters from merge/separate had ID of \texttt{-1}
\item Now, \alert{merge}: new ID is same as first input.
\item Now, \alert{separate}: new IDs all same as the single input.
\end{itemize}
\item Cluster IDs can be forcibly (re)enumerated:
\begin{itemize}
\item Past: \alert{every} clustering function set IDs to ``tree order'' on exit
\item Now: \texttt{Grouping::enumerate(string order, start=1)} is available with \texttt{order}:
\begin{description}
\item[{none}] no (re)enumeration, IDs are as made
\item[{``tree''}] use order of children clusters
\item[{``size''}] use order determined by \texttt{cluster\_less}
\end{description}
\end{itemize}
\end{itemize}
MABC option: \texttt{cluster\_id\_order} forward to \texttt{enumerate()}, default is ``none''.

\alert{Caveat: idents have no meaning, only rely on them for debugging}.
\end{frame}
\begin{frame}[label={sec:orge73a01c},fragile,shrink=10]{Extension to MABC's Bee dumper}
 I wanted a richer set of Bee dumps: per visitor result and per grouping.
\begin{block}{Extend \texttt{BeePointsConfig} and MABC's configuration options parsing}
\begin{Code}
\begin{Verbatim}
\color{EFD}\EFk{struct} \EFt{BeePointsConfig} \{
    \EFcd{//} \EFc{...}
    \EFo{std}::\EFt{string} \EFv{grouping};
    \EFo{std}::\EFt{string} \EFv{visitor};
\};
\end{Verbatim}
\end{Code}

\begin{description}
\item[{grouping}] Name the grouping to consider, defaults to \texttt{"live"}
\item[{visitor}] Name the \texttt{IEnsembleVisitor} results to dump, defaults to post-loop results.
\end{description}

Prior behavior shoudld be unchanged:
\begin{itemize}
\item Special case handling of \texttt{"img"} Bee type is preserved.
\end{itemize}
\end{block}
\begin{block}{Possible future work}
MABC Bee dumper deserves some factoring and rationalization / reintegration with
the stand-alone Bee-dumper component.
\end{block}
\end{frame}
\begin{frame}[label={sec:orgc234129},fragile,shrink=10]{Slightly off topic: \texttt{wire-cell-python} and \texttt{wcpy bee}}
 \begin{block}{Simpler, unified CLI brings a global \texttt{-{}-{}help} and one-stop shopping}
\begin{verbatim}
$ wire-cell-<name> <command>  # maps to:
$ wcpy <name> <command>
\end{verbatim}
\end{block}
\begin{block}{Can now use \texttt{uv} to build/install/run}
\begin{verbatim}
$ uv tool install git+https://github.com/wirecell/wire-cell-python
$ wcpy
\end{verbatim}
\end{block}
\begin{block}{Added a \texttt{wirecell.bee} module and ``\texttt{wcpy bee}'' command}
\begin{verbatim}
$ wcpy bee summary bee.zip
$ wcpy bee diff bee1.zip bee2.zip
\end{verbatim}
Limit scope with: \texttt{-{}-{}depth \{point,shape,cluster,grouping,ensemble\}} 
\end{block}
\begin{block}{Future \texttt{wirecell.bee} feature additions}
\begin{itemize}
\item ``Rand index'', ``chamfer'' and/or other point-cloud distance metrics for approximate, ``geometrical'' diffs.
\item Add a ``\texttt{wcpy bee upload}'' command replacing WCT's \texttt{bee-upload} shell script.
\item Implement the actual Bee server code for easier ``self-hosting''.
\end{itemize}
\end{block}
\end{frame}
\begin{frame}[label={sec:org0db3257},fragile]{Cluster cache management}
 \begin{block}{The general facade caching mechanism was being totally ignored.}
Perhaps because it was not sufficient!

It now allows for \alert{fine-grained} cache filling / invalidating.
\end{block}
\begin{block}{Cached \texttt{Cluster} results are now \alert{all} in a new \texttt{struct ClusterCache}}
Fine-grained cache management pattern:

\begin{Code}
\begin{Verbatim}
\color{EFD}\EFcd{//} \EFc{Top of some Cluster method}
\EFk{auto}\& \EFv{data} = cache().data;  \EFcd{//} \EFc{non-const reference}
\EFk{if} (data.empty()) \{         \EFcd{//} \EFc{exact test depends on data type}
    data = ...;             \EFcd{//} \EFc{fine-grain cache fill}
\}
\EFcd{//} \EFc{...use or return the "data"}
\end{Verbatim}
\end{Code}
\end{block}
\begin{block}{Do not add more \texttt{Cluster} state and cache.}
But if you must, add members to \texttt{ClusterCache} and not directly to \texttt{Cluster}.
\end{block}
\end{frame}
\begin{frame}[label={sec:org3c5425e},fragile,shrink=10]{Graph type}
 \begin{block}{Graphs made/used by Dijkstra's shortest path and ``examine graph'' are now of type:}
\begin{Code}
\begin{Verbatim}
\color{EFD}\EFk{using} \EFt{Graph} = \EFo{boost}::\EFt{adjacency\_list}<
    \EFo{boost}::vecS,        \EFcd{//} \EFc{vertices}
    \EFo{boost}::vecS,        \EFcd{//} \EFc{edges}
    \EFo{boost}::undirectedS, \EFcd{//} \EFc{edge direction (none)}
    \EFo{boost}::\EFt{property}<\EFo{boost}::vertex\_index\_t, \EFt{size\_t}>,
    \EFo{boost}::\EFt{property}<\EFo{boost}::edge\_weight\_t, \EFt{float}> 
    >;
\end{Verbatim}
\end{Code}
\begin{itemize}
\item The \texttt{vecS} \alert{vertex descriptor} assures it is also an \alert{index}.
\begin{itemize}
\item Our code was conflating the two.  It worked only by accident.
\end{itemize}
\item The \texttt{vecS} container assures order stability (\texttt{setS} explicitly not guaranteed)
\item Now as before, \alert{no vertex removal} after initial graph construction.
\end{itemize}
\end{block}
\begin{block}{Dijkstra's shortest paths distances: \texttt{int} \(\to\) \texttt{double}.}
Use of \texttt{int} caused many ``distance ties'', \texttt{double} makes ties less likely.
\begin{itemize}
\item Tie-breaking strategy depends on use of \texttt{vecS} vs \texttt{setS} for vertices.
\item Using \texttt{vecS} may allow more stable tie-breaking, but this is not yet confirmed.
\end{itemize}
\end{block}
\end{frame}
\begin{frame}[label={sec:orgfd36f69},fragile,shrink=10]{Graph construction}
 \begin{block}{Basic construction always defines number of vertices}
\begin{Code}
\begin{Verbatim}
\color{EFD}\EFk{auto} \EFv{graph} = \EFo{std}::make\_unique<\EFo{Weighted}::Graph>(cluster.npoints());
\end{Verbatim}
\end{Code}
\end{block}
\begin{block}{Several ways to form edge connections via one or more functions}
\begin{Code}
\begin{Verbatim}
\color{EFD}connect\_graph\_<flavor>(cluster, ...);
\end{Verbatim}
\end{Code}
Connection ``flavors'': ``basic'', ``ctpc'', ``closely'', ``relaxed'' (overclustering protection).
\end{block}
\begin{block}{Construction and connections combined in graph ``maker'' functions}
\begin{verbatim}
auto graph = make_graph_<flavor>(cluster, ...);
\end{verbatim}
\end{block}
\begin{block}{User code gets same graphs as before.}
\begin{itemize}
\item Dijkstra's shortest paths: ``closely + basic'' or ``closely + ctpc + basic''.
\item Examine graph: ``closely + relaxed''.
\end{itemize}
\end{block}
\end{frame}
\begin{frame}[label={sec:org48e90bf},fragile,shrink=10]{Cluster graph algorithm caching}
 \begin{block}{New \texttt{Cluster} method and sub-object for graph algorithms}
\begin{Code}
\begin{Verbatim}
\color{EFD}\EFcd{//} \EFc{The "basic" (non-ctpc) graph, or get previously made GA.}
\EFk{const} \EFo{Graphs}::\EFo{Weighted}::\EFt{GraphAlgorithms}\& 
\EFf{graph\_algorithms}(\EFk{const} \EFo{std}::\EFt{string}\& \EFv{flavor} = \EFs{"basic"}) \EFk{const};
\EFcd{//} \EFc{The "ctpc" and "relax" graph flavors need detector info}
\EFk{const} \EFo{Graphs}::\EFo{Weighted}::\EFt{GraphAlgorithms}\& 
\EFf{graph\_algorithms}(\EFk{const} \EFo{std}::\EFt{string}\& \EFv{flavor},
                 \EFo{IDetectorVolumes}::\EFt{pointer} \EFv{dv}, 
                 \EFo{IPCTransformSet}::\EFt{pointer} \EFv{pcts}) \EFk{const};
\end{Verbatim}
\end{Code}
\end{block}
\begin{block}{\texttt{GraphAlgorithms} hold graph and are cached by \texttt{Cluster}}
\begin{itemize}
\item Graphs to use come in \alert{basic} and \alert{ctpc} flavors (as before - based on \texttt{use\_cptc} option).
\item The \texttt{GraphAlgorithms} object encapsulates the graph and derivative results
\begin{itemize}
\item Maps from \alert{source point index} to a \texttt{ShortestPaths} object
\item \texttt{ShortestPaths} yields and caches map from \alert{target point index} to the \alert{shortest path}.
\end{itemize}
\item \texttt{Cluster} caches up to two \texttt{GraphAlgorithms} objects based on \texttt{"basic"} and \texttt{"ctpc"} names.
\end{itemize}
\end{block}
\begin{block}{Future extensions}
\begin{itemize}
\item More graph algorithms in \texttt{GraphAlgorithms}
\end{itemize}
\end{block}
\end{frame}
\begin{frame}[label={sec:org22611a9},fragile]{Comment on \texttt{GraphAlgorithms} and ``bare'' graphs}
 \begin{block}{Right now, \texttt{Cluster} only has \texttt{GraphAlgorithms}}
\begin{itemize}
\item GA's \alert{do not expose their graphs}.
\item User can not ``get'' nor modify the underlying graph.
\begin{itemize}
\item User can only chose what graph ``flavor'' to construct.
\end{itemize}
\end{itemize}
Primarily, this restriction is for cache and conceptual simplicity.
\end{block}
\begin{block}{Future usage may require more intimate graph access (eg Steiner).}
\begin{itemize}
\item We will figure out what best to do once construction/mutation patterns are
understood.
\end{itemize}
\end{block}
\end{frame}
\begin{frame}[label={sec:org3ed3d2e},fragile]{Comment on graph serialization - a non feature (for now?)}
 \begin{block}{For now, we have none}
\begin{itemize}
\item Graphs are purely cache on \texttt{Cluster} and not saved to PC tree.
\item Thanks Haiwang for pointing out the wisdom.
\end{itemize}
\end{block}
\begin{block}{Clear idea for providing it, if needed.}
I have code to perform serialization with \texttt{PointCloud::Dataset}.

\begin{itemize}
\item It is laborious written for each C++ type of \texttt{boost::graph}.
\item Also I have code for a \alert{generic graph I/O} system
\begin{itemize}
\item PC datasets, files (XML, JSON), and more.
\item Requires WCT gain a dependency on Boost's serialization library.
\end{itemize}
\end{itemize}
\end{block}
\end{frame}
\begin{frame}[label={sec:orgaa90468},fragile,shrink=10]{Factor \texttt{ClusteringRetile} \(\to\) \texttt{RetileCluster}}
 \begin{block}{Why do this?}
\begin{itemize}
\item \texttt{ClusteringRetile} operates at \texttt{Grouping} level.

\item Pat. rec. will need to ``retile'' individual clusters to make a temporary.
\end{itemize}
\end{block}
\begin{block}{The body of \texttt{ClusteringRetile}'s main loop moved into a \texttt{RetileCluster}}
\begin{Code}
\begin{Verbatim}
\color{EFD}\EFcd{//} \EFc{New Interface:}
\EFo{std}::\EFt{unique\_ptr}<\EFt{node\_t}> \EFo{IPCTreeMutate}::\EFf{mutate}(\EFt{node\_t}\& \EFv{node}) \EFk{const};
\end{Verbatim}
\end{Code}

\begin{itemize}
\item Uses PC tree \alert{node}, not \alert{facade} due to ownership issues.
\item Named ``mutate'' as \texttt{separate()/merge()} requires changes (though they be temporary).
\begin{itemize}
\item A const \texttt{IPCTreeTransform::transform(const node\_t\&)} is also now available.
\end{itemize}
\item Return may be \texttt{nullptr}.
\end{itemize}
\end{block}
\begin{block}{Leaves \texttt{ClusteringRetile} very short}
Handles creation of a ``shadow'' grouping in the \texttt{Ensemble} node.
\begin{itemize}
\item Loops over clusters, calls \texttt{IPCTreeMutate::mutate()}.
\end{itemize}
\end{block}
\end{frame}
\begin{frame}[label={sec:org5065254},fragile]{Misc API/code cleanups}
 \begin{itemize}
\item \texttt{Cluster::get\_pca()} only, method.  It returns \texttt{struct PCA} with \texttt{.center/.axis/.value}.

\item Try to make all class attributes start with \texttt{m\_}.

\item Try to make \texttt{this->} prefix on internal \texttt{Cluster} method calls to help mark targets for future refactoring.

\item Match \texttt{ClusteringFuncs\{.h,cxx\}} file names.
\end{itemize}
\end{frame}
\begin{frame}[label={sec:org722dc82},fragile]{Open issues - PCA}
 Stand-alone PCA is needed for \texttt{clus} \#423

\begin{itemize}
\item We have a PCA calculator in \texttt{WireCell::Array} for points already in an \texttt{Eigen:Matrix}.
\item Any ``point type generic'' PCA calculator may be more trouble than it is worth.
\end{itemize}

Since I am unsure what ``best'' to do, I put this on hold until we hit the need.
It should be easy to provide then.
\end{frame}
\begin{frame}[label={sec:orgcffad1c},fragile]{Open issues - Cluster complications}
 \begin{itemize}
\item \texttt{Cluster} facade has grown state not related to caching and it needs control \#420
\item Copy-pasted \texttt{Cluster} state transfer code needs to be replaced with \texttt{Cluster::from()} \#424
\end{itemize}

There's probably no end to these.  I think main thing now is to go through and
replace the multi-line transfer of Cluster state (default scope, etc) to the
single call to \texttt{cluster->from(\&other\_cluster)} in all the clustering functions.

I can do this but for now I'm just tired of the cleanup.
\end{frame}
\begin{frame}[label={sec:org7305683},fragile]{Open (closed?) issues - ambiguous names}
 \begin{itemize}
\item wcp-porting-img's \href{https://github.com/HaiwangYu/wcp-porting-img/issues/7}{Ambigously named BlobSampler live/dead pairs in ``pdhd'' test.}
\end{itemize}

At this point, I suggest we close this Issue in favor and copy WCT's

\begin{verbatim}
clus/test/test-porting/pdhd/clus.jsonnet
\end{verbatim}

Note, this uncovered

\begin{itemize}
\item Small blobs can have no ``stepped'' sample points. \#425
\end{itemize}

Fixing that involves adding a \texttt{cm.pointed()} clustering function at the front of
MABC's pipeline.

\begin{itemize}
\item This is done in WCT's \texttt{pdhd/clus.jsonnet}.

\item It will change the results but not perceptively in Bee.
\end{itemize}
\end{frame}
\begin{frame}[label={sec:org1569474}]{Open issues - BlobSampler API}
\begin{itemize}
\item BlobSampler API has become broken which lays a trap for the user. \#426
\end{itemize}

Not sure what to do about this one as it really breaks things and I'm tired of
doing cleanup for other's breakage.  See issue for details.
\end{frame}
\end{document}
