~c-tunnell1/+junk/chepdq2012

\documentclass[a4paper]{jpconf}

\usepackage{graphicx}

\begin{document}

\title{MAUS: MICE Analysis User Software \jpcs}

 

\author{M. Jackson (EPSRC)\footnote{We would like to acknowledge the assistance of the Software Sustainability Institute. The work carried out by the SSI is supported by EPSRC through grant EP/H043160/1.}, D. Rajaram (IIT) and C.D. Tunnell (U. Oxford) \footnote{test}}

 

\address{}

 

\ead{michaelj@epcc.ed.ac.uk, \{durga,tunnell\}@fnal.gov}

 

\begin{abstract}

The Muon Ionization Cooling Experiment (MICE) has developed the MICE Analysis User Software (MAUS) to simulate and analyze experimental data.  It serves as the primary codebase for the experiment and provides, for example, online data quality checks and offline batch simulation and reconstruction. The code is structured in a framework inspired by Map-Reduce to allow parallelization whether on a personal machine or in the control room. Various software engineering practices from industry are also used to ensure correct and maintainable physics code, which include unit, functional and integration tests, continuous integration and load testing, code reviews, and distributed version control systems. Lastly, there are various small design decisions like using JSON as the data structure, using SWIG to allow developers to write components in either Python or C++, or using the SCons python-based build system that may be of interest to other experiments.

\end{abstract}

 

%\section{Introduction}

%1. Overview of MICE goals\\

%2. MICE software requirements and goals\\

%3. Software framework\\

%4. Software components\\

%5. Data structure\\

%6. Lessons from Industry \\

%6. Conclusions\\

 

\section{The MICE Experiment}

 

The Muon Ionization Cooling Experiment (MICE) is based at the Rutherford Appleton Laboratory and aims to demonstrate the reduction of phase space for muon beams.  This R\&D is important for ensuring efficient operation of proposed accelerators using muons beams (See \cite{c:IDR} and references there-in) and there have been various phases of this R\&D program: over the last decade there have been numerous construction phases interweaved with running periods.  Given the experiment is constantly changing and the long time-scales inherent with conducting such an R\&D, the need arises to ensure long-term correctness and maintainability of the software used for the experiment.  This goal is complicated by the 5 detector technologies used within the experiment.

 

\section{Software Requirements}

 

The MICE analysis software must simultaneously be both particle physics code and accelerator physics code. The particle physics functionality includes features like simulating electronics respond or reconstructing tracks, whilst the accelerator physics requires the computation of transfer matrices and Twiss parameters. Both types of functionality require knowledge of, for example, the magnetic fields and geometry thus requiring a single software scope.

 

The requirements imposed upon the software were previously addressed by the G4MICE package \cite{g4mice}, created in 2002. Test coverage and documentation were missing for the much of the code base making development, use and verification of the code challenging. This is a frequent problem in physics and industry. The extraction principle outlined in \cite{refactoring} was used to refactor the code, where \emph{refactoring} is the systematic process of restructuring code to address changing specifications.

 

Since it was inefficient to attempt to understand the previous code due to lost expertise, the code was frozen such that no changes were allowed and wrappers were written such that the code could interface with a new Python framework. To improve the project, small pieces of code were gradually written to replace the old frozen functionality.  These new codes had quality requirements: good comments, a style guide, and tests.  This made it possible to slowly improve the quality and maintainability of the code base while retaining existing functionality.

 

\section{MAUS}

 

The MICE  Analysis User Software (MAUS) has been official MICE  software since 2010 and has prepared MICE for more complex data taking scenarios with higher data rates \cite{maus}.  The goal was to restructure the code into a Map-Reduce inspired \cite{mapreduce} data flow in order to simplify the interfaces that developers have to follow and aid running the code in parallel.  It was felt that Map-Reduce parallelizes particle physics problems in a useful fashion but the API was simplified to have \emph{transformers} and \emph{mergers} instead of maps and reduces.

 

The basic unit of information is ``spill-level", which corresponds to a single beam extraction.  Spills are independent, thus simplifying parallelization.   For example, each ``transform'' should process a spill by converting the binary DAQ output to a processable data structure and then applying a track fitting routine.  A similar thing can be done to Monte Carlo (MC) simulation of the apparatus.  ``Merger'' allows functionality that requires access to the entire data set of a single spill: evolution of parameters over time, making histograms, and so forth.

 

The JSON data structure is used to represent a spill in order to aid developers in extending it and users in understanding it.  An example spill input is:

 

\begin{verbatim}

{

    "mc_particles": [

        {

            "primary": {

                "energy": 210.0, 

                "momentum": {

                    "x": 0.0, 

                    "y": 0.0, 

                    "z": 1.0

                }, 

                "particle_id": 13, 

                "position": {

                    "x": 0.0, 

                    "y": -0.0, 

                    "z": -5000.0

                }, 

                "random_seed": 10, 

                "time": 0.0

            }

        }

    ]

}

\end{verbatim}

 

 

\begin{figure*}[tb]

    \centering

    \includegraphics*[width=168mm]{outfile}

    \caption{An visual representation of a MAUS control macro that illustrates the data flow.}

    \label{dataflow}

\end{figure*}

\noindent

and an example macro that controls MAUS is:

 

\begin{verbatim}

import MAUS

 

# File with particles to simulate                                                                                                                                                     

my_input = MAUS.InputJSON("evts.json")

 

# Create an empty array of maps, then                                                                                                                                                     

# populate it with the functionality you                                                                                                                                                     

# want to use.                                                                                                                                                                               

my_map = MAUS.MapGroup()

 

# Add geant4 Monte Carlo simulation                                                                                                                                                          

my_map.append(MAUS.MapSimulation())

 

# Add electronics models                                                                                                                                                                     

my_map.append(MAUS.MapTOFDigitization())

my_map.append(MAUS.MapTrackerDigitization())

 

# Create set of standard demo plots                                                                                                                                                 

my_reduce = MAUS.ReduceMakeDemoPlots()

 

# Where to save output?                                                                                                                                                                      

filename = `simulation.out'

 

# Create uncompressed file object.                                                                                                                                                           

# 'w' means write.                                                                                                                                                                           

output_file = open(filename, `w')

 

# Then construct a MAUS output component                                                                                                                                                     

my_output = MAUS.OutputJSON(output_file)

 

#  The Go() drives all the components you                                                                                                                                                    

#  pass in, then check the file defined                                                                                                                                                      

#  above for the output                                                                                                                                                                      

MAUS.Go(my_input, my_map,

        my_reduce, my_output)

\end{verbatim}

 

\noindent

where dataflow in MAUS is illustrated in Fig.~\ref{dataflow}.  The macro language is Python but components can be written in either Python or C++.

 

SWIG \cite{swig} is used to make Python bindings to C++ code which are created automatically.  The experience with using SWIG is a bit mixed: SWIG is good for well-defined APIs like that defined by the transforms and merges but it proved difficult to use SWIG to reveal common C++ routines that would have been useful within Python code (ex. magnetic fields).  The Boost::python libraries seem to be easier to use for the HEP use-case but their difficulty to install made them infeasible to use.

 

\section{Applying Lessons from Industry}

 

Knowledge gained within industry can be applied and enable the project to run more smoothly.   Various industry procedures were tested in developing MAUS.

 

\subsection{Project Management and Issue Tracker}

 

A paradigm shift in how the code was written came naturally with the change in how the project was managed. Before any code was written, a project management website was set up that included a wiki and issue tracker using the Redmine software.  This allowed people to keep track of task assignment, current bugs, and feature requests.  It is a vital tool for establishing the status of various blocks of work while simultaneously providing a useful historical record and institutional memory.  The decision to use Redmine seems to have been a good one as the ease of its use allowed for the expansion of this project management tool to other parts of the MICE project.

 

\subsection{Code Reviews}

 

Code reviews are standard practice in industry but rare within physics mostly due to the man-power limitations within the software projects.   New code requires an hour of review before entering the trunk with other communal code.    In addition to tracking down bugs, the review process also helps spread knowledge of the project between developers.  It helps people learn from one another while simultaneously decreasing the reliance on specific developers.

 

\subsection{Static Code Analysis}

 

Static code analyzers such as Coverity \cite{coverity} were used.   The purpose of this type of tool is to inspect code to determine if there are conditions the code can enter that may lead to unexpected behavior.  For example, if a variable is not initialized and there is a way for the variable to be used that would lead to a segmentation fault, this tool will alert the user.

 

The static code analyzer finds problems of varying degrees of severity and human intervention is required to categorize them. Given that, it is inefficient to use static code analyzers on legacy code since it takes an unrealistic amount of time to process the wide range of errors.  The optimal use case is only to rectify problems observed in new code, thus incrementally improving the code base.  

 

However, it was decided to abandon static code analysis since the gains did not merit the time required.

 

\subsection{Tests and Continuous Integration}

 

Unit tests are small pieces of code that test other small pieces of code.  They are meant to be granular, deterministic, and repeatable.  Their purpose is to allow the person developer to know if they have broken preexisting code.  These tests aid in creating releases since one can verify that the code is still functional.  If bugs are found, new tests are added to make sure the bug never resurfaces.  This type of development also allows one to quickly narrow down the source of a problem.   The unit test coverage within MAUS has been useful for developers to know when a piece of code has broken, but most importantly unit tests help remove the fear of changing code that does not ``belong'' to them.

 

The entire system is checked by integration tests that execute at the

application level. For example, a large statistics simulation could be

used to verify that physics quantities have not changed within

statistical uncertainties.  These have proven to be the most useful tests since they help ensure that the physics does not change.

 

Jenkins \cite{jenkins} performs continuous integration tests of the code. This tool

runs the test suite in a number of different installation environments

every time code is committed. A distributed version control system

called Bazaar \cite{bzr} is used and code from every user is tested before it

becomes communal.

 

These tools have been vital to the project since developers are alerted

to broken code. Jenkins is able to try to compile and test the code on a

wide range of Linux and Mac platforms to ensure that the code can be

deployed to any system. Continuous integration complements unit and integration tests

because the frequent running of unit tests allows code developers to  know instantly where and when a problem was introduced into the code base.

 

\subsection{Release Cycle}

 

Code that has been tested as described above is periodically released.  Major releases occur every few months and minor releases are biweekly.  The limiting factor on the timescale for minor releases is how long it takes to develop and test new code.  This quick release cycle means that bugs are quickly resolved.

 

 

\section{Future}

 

The MAUS effort within the MICE experiment has proven to be a successful collaboration physicists and software engineers.  There are currently about ten active developers working as a team and using a wide range of tools and methods.   A wealth of knowledge and experience exists in the software engineering community and taking advantage of that knowledge has helped MICE.

 

%\section{Figures and figure captions}

%Figures must be included in the source code of an article at the appropriate place in the text %not grouped together at the end. 

 

%Each figure should have a brief cap%tion describing it and, if 

%necessary, interpreting the various lines and symbols on the figure. 

%As much lettering as possible should be removed from the figure itself and 

%included in the caption. If a figure has parts, these should be 

%labelled ($a$), ($b$), ($c$), etc. 

%\Tref{blobs} gives the definitions for describing symbols and lines often

%used within figure captions (more symbols are available

%when using the optional packages loading the AMS extension fonts).

 

%\begin{table}[h]

%\caption{\label{blobs}Control sequences to describe lines and symbols in figure 

%captions.}

%\begin{center}

%\begin{tabular}{lllll}

%\br

%Control sequence&Output&&Control sequence&Output\\

%\mr

%\verb"\dotted"&\dotted        &&\verb"\opencircle"&\opencircle\\

%\verb"\dashed"&\dashed        &&\verb"\opentriangle"&\opentriangle\\

%\verb"\broken"&\broken&&\verb"\opentriangledown"&\opentriangledown\\

%\verb"\longbroken"&\longbroken&&\verb"\fullsquare"&\fullsquare\\

%\verb"\chain"&\chain          &&\verb"\opensquare"&\opensquare\\

%\verb"\dashddot"&\dashddot    &&\verb"\fullcircle"&\fullcircle\\

%\verb"\full"&\full            &&\verb"\opendiamond"&\opendiamond\\

%\br

%\end{tabular}

%\end{center}

%\end{table}

 

 

%Authors should try and use the space allocated to them as economically as possible. At times it %may be convenient to put two figures side by side or the caption at the side of a figure. To put f%igures side by side, within a figure environment, put each figure and its caption into a %minipage with an appropriate width (e.g. 3in or 18pc if the figures are of equal size) and then %separate the figures slightly by adding some horizontal space between the two minipages (e.g. %\verb"\hspace{.2in}" or \verb"\hspace{1.5pc}". To get the caption at the side of the figure add %the small horizontal space after the \verb"\includegraphics" command and then put the %\verb"\caption" within a minipage of the appropriate width aligned bottom, i.e. %\verb"\begin{minipage}[b]{3in}" etc (see code in this file used to generate figures 1--3).

 

%Note that it may be necessary to adjust the size of the figures (using optional arguments to %\verb"\includegraphics", for instance \verb"[width=3in]") to get you article to fit within your %page allowance or to obtain good page breaks.

 

%\begin{figure}[h]

%\begin{minipage}{14pc}

%\includegraphics[width=14pc]{name.eps}

%\caption{\label{label}Figure caption for first of two sided figures.}

%\end{minipage}\hspace{2pc}%

%\begin{minipage}{14pc}

%\includegraphics[width=14pc]{name.eps}

%\caption{\label{label}Figure caption for second of two sided figures.}

%\end{minipage} 

%\end{figure}

 

%\begin{figure}[h]

%\includegraphics[width=14pc]{name.eps}\hspace{2pc}%

%\begin{minipage}[b]{14pc}\caption{\label{label}Figure caption for a narrow figure where the %caption is put at the side of the figure.}

%\end{minipage}

%\end{figure}

 

%Using the graphicx package figures can be included using code such as:

%\begin{verbatim}

%\begin{figure}

%\begin{center}

%\includegraphics{file.eps}

%\end{center}

%\caption{\label{label}Figure caption}

%\end{figure}

%\end{verbatim}

 

\section*{References}

\begin{thebibliography}{9}

\bibitem{iopartnum} IOP Publishing is to grateful Mark A Caprio, Center for Theoretical Physics, Yale University, for permission to include the {\tt iopart-num} \BibTeX package (version 2.0, December 21, 2006) with  this documentation. Updates and new releases of {\tt iopart-num} can be found on \verb"www.ctan.org" (CTAN). 

\end{thebibliography}

 

\end{document}