% TEXINPUTS=.:$HOME/git/bvtex: latexmk  -pdf ggd.tex


\documentclass[10pt,xcolor=dvipsnames]{beamer}
\input{defaults}

\input{beamer/preamble}
\usepackage[outline]{contour}

\definecolor{bvtitlecolor}{rgb}{0.98, 0.92, 0.84}
\definecolor{bvoutline}{rgb}{0.1, 0.1, 0.1}

\newcommand{\worch}{\textit{worch}\xspace}
\newcommand{\waf}{\textbf{waf}\xspace}

\renewcommand{\bvtit}{GeGeDe}
\renewcommand{\bvtitle}{\LARGE \textcolor{DarkOrchid}{General Geometry Description}}
\renewcommand{\bvevent}{LBNE Collab Meeting, July/Aug 2014}
\renewcommand{\bvbeamerbackground}{}

\begin{document}
\input{beamer/title.tex}
\input{beamer/toc.tex}

\section{Overview}

\subsection{Motivation}

\begin{frame}
  \frametitle{Motivation}

  LBNE S\&C determined that LBNE needs a Geometry
  Information Management strategy and system.
  \begin{itemize}
  \item Many geometries: multiple detectors (35t/ND/FD) plus beamline.
  \item LBNE still in design phase, need variants on each geometry.
  \item 3 (and growing) different main simulation applications.
  \item Internationally distributed effort. 
  \end{itemize}

  \vspace{5mm}

  This effort is also in keeping with some of the plans presented at
  the LBNE S\&C review last May.

\end{frame}

\subsection{Recent History}

\begin{frame}
  \frametitle{Happy Coincidences}
  \small
  \begin{itemize}
  \item Both Tyler and I have been independently concerned about geometry.
    \begin{itemize}
    \item Tyler from the high-level application view (getting things done!)
    \item Me from a general, cross-application, infrastructure view.
    \end{itemize}
  \item Tyler expressed concerns regarding current geometry generation
    via \\ ``\textbf{the Perl script}'' \textit{(cue ominous music)}
    \begin{itemize}
    \item \textit{``Impossible to work w/other people on it at the same time''}
    \item Concerns for existing \textbf{FD} and new \textbf{35t} and \textbf{ND} geometries.
    \item Thinking about a high-level, modular reimplementation in \textbf{Python}
    \end{itemize}
  \item In parallel I was thinking of a bottom-up, layered system in
    \textbf{Python} based on some prior
    development\footnote{\url{http://github.com/brettviren/cowbells}}.
  \end{itemize}

  \begin{itemize}
  \item[$\rightarrow$] complementary approaches meeting each other at an obvious layer.
  \item[$\rightarrow$] the time was ripe to get something in Tyler's hands ASAP.
  \end{itemize}

  The low-level half is presented today: 
  \begin{center}
    General Geometry Description (GGD or \texttt{gegede})\footnote{\url{http://github.com/brettviren/gegede/}}
  \end{center}


\end{frame}

\subsection{Components}

\begin{frame}
  \frametitle{Aspects of GGD}

  The \textbf{General Geometry Description} provides

  \begin{description}
  \item[authoring] a human-oriented way to develop geometry descriptions
  \item[persistence] keeping geometry information for later use
  \item[provenance] what geometry was used, where it came from
  \item[visualization] methods to graphically represent the geometry
  \item[validation] checks for correctness
  \item[conversion] converting between different representations
  \end{description}

  \vspace{4mm}

  While still in development, a lot of support exists:

  \begin{itemize}
  \item can start authoring geometry \texttt{today}
  \item can convert to GDML, but this still needs testing
  \end{itemize}

\end{frame}

\section{The General Geometry Description Package}

\begin{frame}[fragile]
  \frametitle{Geometry Geometry Description package}

  \vspace{5mm}

  Provides human-oriented, geometry description authoring in \textbf{layers}:

  \vspace{2mm}

  \begin{description}
  \item[params] high-level, user-accessible \textbf{configuration} parameters
  \item[builders] reusable and hierarchical ``chunks'' of code responsible for \textbf{constructing} portions of the overall geometry
  \item[objects] comprehensive system for describing \textbf{Constructive Solid Geometry} objects
  \item[exporters] conversions from objects to various \textbf{exchange formats} including GDML, ROOT and AGDD.
  \end{description}

  \vspace{-2mm}

  \begin{center}
    \includegraphics[width=0.9\textwidth]{layers.pdf}
  \end{center}

\end{frame}

\subsection{Configuration Layer}

\begin{frame}
  \frametitle{Configuration Layer}
  \begin{itemize}
  \item Provides user-configuration of high-level parameters.
  \item Simple text file with \textbf{named sections} holding \textbf{key/value} pairs.
  \item Sections mapped to ``\texttt{builder}'' objects (next section)
    \begin{itemize}
    \item specify the Python class holding the builder code
    \item specify names of zero or more ``sub-builders''
    \end{itemize}
  \item Pervasive and mandatory use of \textbf{correct units} for literal values!
  \item Flexible value type support (in fact, interpreted by Python)
  \item Configuration is \textbf{fully optional}, builder authors may:
    \begin{itemize}
    \item elect to ignore the configuration layer and ``hard code''
    \item still create sub-builders purely in code
    \item or some mix of user-configuration and hard-coding
    \end{itemize}
  \item If used, beyond a couple reserved keys, authors are free to
    define any configuration schema for their builder.
  \end{itemize}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Example Configuration}
\small
\begin{verbatim}
[everything]  
class = mymodule.mybuilders.WorldBuilder
subbuilders = ["farsite", "nearsite", "testhall"]
size = Q("1000km")

[farsite]
class = mymodule.mybuilders.SiteBuilder
subbuilders = ["lardet"]
wireangle = Q("45*deg")
# etc, ...
\end{verbatim}

  \begin{itemize}
  \item Each section names a \textbf{builder instance}.
  \item Either specify a ``world'' builder or first one is taken by default.
  \item The \texttt{class} and \texttt{subbuilders} are the only reserved keys.
    \begin{itemize}
    \item Interpreted by the \texttt{gegede.main} management layer.
    \item Each builder free to expect/interpret any additional keys.
    \end{itemize}
  \item Use \texttt{Q("...")} (\texttt{Q} for ``quantity'') for expressing units\footnote{\url{http://pint.readthedocs.org/}}.
  \end{itemize}

\end{frame}

\subsection{Builders Layer}

\begin{frame}[fragile]
  \frametitle{Builders}
  \begin{itemize}
  \item Reusable chunk of code that ``knows'' how to \textbf{construct} some geometry
    and may delegate some construction to sub-builders.
  \item Each builder:
    \begin{itemize}
    \item exposes one or more logical volumes (LV) to the parent builder.
    \item properly places (PV) any subbuilder's LVs into its own LVs
    \end{itemize}
  \item Builders may explicitly create subbuilders or rely on implicit
    creation via the configuration layer.
  \end{itemize}

  \includegraphics[width=\textwidth]{builders.pdf}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Builder details}

  \footnotesize

  \begin{lstlisting}[language=Python]
class MyBuilder(gegede.builder.Builder):

  def configure(self, dx='1m', dy='2m', dz='3m', **kwds):
    # ... specify any default/expected configuration
    # ... incorrect units are caught as errors!
    # ... configure self, typically trivially
    self.size = (dx,dy,dz)

  def construct(self, geom):
    # ... construct geometry with ``geom'' object
    box = geom.shapes.Box(self.name+'_shape', *self.size)
    # ... make LV with box, etc
    for sb in self.builders:
      # place top-level LV of any sub-builders
  \end{lstlisting}

  \begin{description}
  \item[\texttt{configure()}] used to transmit any configuration parameters, typically as taken from the configuration file section of the same name as the builder.
  \item[\texttt{construct()}] actual construction using configuration.  Any subbuilders will have already done their construction so builder may use their LVs
  \end{description}

\end{frame}

\subsection{Geometry Object Layer}

\begin{frame}
  \frametitle{Geometry Objects} 

  GeGeDe has \textbf{comprehensive} coverage of typical CSG schema:
  \begin{description}
  \item[shapes] (aka ``solids'') such as box, tubs, sphere, etc
  \item[matter] elements, isotopes, mixtures, materials, etc
  \item[structure] rotations, positions, logical and physical volumes
  \end{description}

  Geometry objects follow a \textbf{schema} asserting:
  \begin{itemize}
  \item the above class categories
  \item class names their expected data members
  \item prototypes for every data member 
    \begin{itemize}
    \item prototypes assert \textbf{units}, where appropriate
    \item instances \textbf{must} use compatible units or exception raised!
    \end{itemize}
  \end{itemize}

\end{frame}

\subsection{Exporter Layer}

\begin{frame}
  \frametitle{Exporters}

  Geometry objects are patterned after those from Geant4 but are
  otherwise generic.

  \vspace{2mm}

  Exporters produce alternative representations:

  \begin{description}
  \item[GDML] for Geant4 in LArSoft/g4lbne.  Initial exporter exists but not complete.  Uses \texttt{lxml.etree} for assuring valid XML.
  \item[ROOT] for Geant4-free contexts such as data reconstruction.
    \\ (to do, will bring in optional dependency on PyROOT)
  \item[AGDD] for feedin to the useful GraXML viewer (to do)
  \item[etc...] exporters are easy to develop.  The initial GDML
    exporter took $\sim$2 hours to write.
  \end{description}

  \begin{itemize}
  \item Consider exporter output as \textbf{data transfer} only.  
  \item The \textbf{builder code + configuration file} is definitive.
  \end{itemize}


\end{frame}

\section{Future Work}

\begin{frame}
  \frametitle{Future Work}

  \begin{itemize}
  \item Schema coverage is not complete.  Still needs:
    \begin{itemize}
    \item Plethora of shapes.  So far only: box, tubs, sphere
    \item Bulk and surface properties.
    \item Want some default material and property objects \\ (ie, ``batteries included'')
    \item A few misc data members to back-fill (eg, LV's pressure and state)
    \item Straight-forward, just a bit tedious.
    \end{itemize}
  \item Add some self-consistency validation at the geometry object level.
  \item Finish the GDML exporter, develop ROOT and AGDD exporters.
  \end{itemize}

  Application geometry experts (Tyler) can already get started writing builders.
\end{frame}

\end{document}

