Merge changes to master, update readme

Documentation/Geant4-GPUSRS.tex

@@ -17,7 +17,7 @@
 \newcommand{\todo}[1]{\textcolor{red}{[TODO: #1]}} \else
 \newcommand{\authornote}[3]{} \newcommand{\todo}[1]{} \fi
 \newcommand{\wss}[1]{\authornote{magenta}{SS}{#1}}
-\newcommand{\ds}[1]{\authornote{blue}{DN}{#1}}
+\newcommand{\ds}[1]{\authornote{blue}{DS}{#1}} %I fixed your comment code again -- DS
 % End Comments ---------------------------------------------------------------
 
 \renewcommand\thesubsubsection{\thesection.\arabic{subsection}.\alph{subsubsection}}
@@ -113,7 +113,9 @@ \subsection{Stakeholders}\label{SubSec_Stakeholders} % Victor
 \end{itemize}
 
 \subsubsection{The Client}
-The clients for the project are the Dr. Buijs and his grad student Wesley Ford, representing the McMaster Engineering Physics Department. The clients proposed the project because they have invested interest in running G4-STORK simulations more efficiently. They will be using the parallelized code to run and study nuclear simulations, and require that the code executes much more quickly to obtain useful data.
+The clients for the project are
+\ds{Unnecessary ``the"}
+Dr. Buijs and his grad student Wesley Ford, representing the McMaster Engineering Physics Department. The clients proposed the project because they have invested interest in running G4-STORK simulations more efficiently. They will be using the parallelized code to run and study nuclear simulations, and require that the code executes much more quickly to obtain useful data.
 
 \subsubsection{The Customer}
 The customer in this case also includes the clients. As such they will be the part of the end-user group that we will cater to.
@@ -131,7 +133,9 @@ \subsubsection{Personas}
 Consider Matt Douglas, a graduate student in the Engineering Physics Department. Matt wants to study how particles in McMaster's nuclear reactor affect each other, given some specific starting conditions, and a very large number of particles. Matt knows how to use the existing G4-STORK program, but it will take weeks to run the computations. Matt inputs his desired number of particles and specific starting conditions into a G4-STORK simulation. He enables the GPU features of the new product, and successfully runs the simulation in a reasonable amount of time. He observes interesting results that would not have been feasible to obtain with the old product.\\
 
 \subsubsection{Priorities Assigned to Users}
-Priority will be given to Wesley Ford, the grad student that proposed the project to Dr. Buijs. He will be the primary user of G4-STORK as it is integral to his current research.
+Priority will be given to Wesley Ford, the grad
+\ds{``graduate"}
+student that proposed the project to Dr. Buijs. He will be the primary user of G4-STORK as it is integral to his current research.
 
 % =============================== Section =============================== %
 \section{Project Constraints}
@@ -140,6 +144,7 @@ \section{Project Constraints}
 \subsection{Mandated Constraints} % Rob
 There are global constraints put in place by the existing software, the stakeholders, and the structure of 4ZP6. The project must be built upon the existing GEANT-4 code, which is used by G4-STORK to run the simulation. The final product must be able to run any code/simulation that ran on the existing software. The software must run in parallel on a NVIDIA GPU. Additionally, the final product needs to be completed by the end of April, 2016. If these global constraints are not met the final product is not acceptable.\\
 
+\ds{Why an NVIDIA GPU? Was that constrained by your client?}
 % ----------------------------- Sub Section ----------------------------- %
 \subsection{Naming Conventions \& Terminology} % Stuart
 Throughout the document, ``the project'', ``the product'', and/or ``the software'' all refer to the modified GEANT-4 code that will include the capability to be run on a GPU. The ``existing software'' refers to the current GEANT-4 simulation toolkit.\\
@@ -192,9 +197,10 @@ \subsubsection{The Context of The Work}
 \begin{figure}[h]
 \includegraphics[width=\textwidth]{WorkContextDiagram} 
 \end{figure} 
-
+\ds{Figure caption?}
 \subsubsection{Work Partitioning}
 All tasks will be divided equally among all members of the development team. The team will work together to initially define the interface for using the GPU to run calculations, and once that is completed each member will independently work on porting specific classes to the GPU. Testing will be done throughout the development by the developers. This ensures that all developers are able to easily debug their contributions.
+\ds{This section is supposed to show a breakdown of the business use cases}
 
 % ----------------------------- Sub Section ----------------------------- %
 \subsection{Business Data Model \& Data Dictionary} % Rob
@@ -217,6 +223,8 @@ \subsection{The Scope of the Product}
 \end{table}
 
 Descriptions of each PUC, referenced by PUC \# are as follows.
+\ds{PUC is not in your glossary}.
+
 \begin{enumerate}
 \item \label{PUC_SimulatingParticles} The software will be used by researchers wishing to simulate large numbers of particles interactions with materials. The researcher sets simulation parameters, including the number of particles, their lifetime, and the material properties before running the simulation. On completion, the program gives back a map of where each particle traveled, so researchers can study where the particles are most probably to end up.
 \end{enumerate}
@@ -243,6 +251,9 @@ \subsection{Functional Requirements} \label{ReqType_Functional}
 {User should be able to quickly enable GPU computations after referencing the documentation. If their hardware is compatible, their project should run with no errors.}
 {High}
 {Created September 29, 2015}
+\ds{Your description shouldn't include ``should be easy". 
+It should be detailing \emph{what} the product is supposed to do.
+Ease of use is a non-functional requirement.}
 \\\\
 
 \requirement
@@ -254,6 +265,7 @@ \subsection{Functional Requirements} \label{ReqType_Functional}
 {Running an existing simulation should execute on the CPU by default as before with no performance regressions and identical results.}
 {High}
 {Created September 29, 2015}
+\ds{This requirement should be split. The default case should have its own requirement.}
 \\\\
 
 \requirement
@@ -265,11 +277,17 @@ \subsection{Functional Requirements} \label{ReqType_Functional}
 {Any computer that can currently run the existing product should be able to run the new product.}
 {Medium}
 {Created September 29, 2015}
+\ds{This requirement should be split. There should be one for detecting hardware and
+one for what to do based on hardware detected.}
+
+\ds{Will users be aware of whether or not their machine can run the code
+on the GPU?}
 
 % ----------------------------- Sub Section ----------------------------- %
 \subsection{Look and Feel Requirements}\label{ReqType_Look} % Victor
 \subsubsection{Appearance Requirements}
 NA -- The scope of the project does not include any visual aspects. Simulations are run through the command line.
+\ds{Then why does your 4.1.b diagram show ``Visualizations rendered and stored?"}
 
 \subsubsection{Style Requirements} 
 \requirement
@@ -281,7 +299,7 @@ \subsubsection{Style Requirements}
 {Any persons with an understanding of the existing project should be able to clearly understand the modified code.}
 {Medium}
 {Created October 6, 2015}
-
+\ds{This is not a requirement for your end-product.}
 % ----------------------------- Sub Section ----------------------------- %
 \subsection{Usability and Humanity Requirements}\label{ReqType_Usabil} % Rob
 
@@ -306,6 +324,7 @@ \subsubsection{Personalization and Internationalization Requirements}
 {A given user with personal (non-technical) barriers to achieving complete satisfaction with the software will be responsible for overcoming such barriers.}
 {Medium}
 {Created October 6, 2015}
+\ds{``Rigorous"}
 
 \subsubsection{Learning Requirements}
 \requirement
@@ -331,6 +350,7 @@ \subsubsection{Accessibility Requirements}
 {A blind university student who potentially has trouble using a shell based operating system may have trouble with the software.}
 {Medium}
 {Created October 6, 2015}
+\ds{Bad fit criterion}
 
 % ----------------------------- Sub Section ----------------------------- %
 \subsection{Performance Requirements}\label{ReqType_Performance}
@@ -373,6 +393,8 @@ \subsubsection{Reliability and Availability Requirements}
 \subsubsection{Robustness or Fault-Tolerance Requirements}
 NA -- The product does not need to maintain standards during an unforseen event. It does not handle any sensitive data, and is not constantly required to be running by its users.
 
+\ds{Shouldn't there be some safeguards in case of an error?}
+
 \subsubsection{Capacity Requirements}
 \requirement
 {Req_Capacity}
@@ -387,6 +409,9 @@ \subsubsection{Capacity Requirements}
 \subsubsection{Scalability Requirements}
 NA -- The product will be used by single researchers, and is run locally on their machines.
 
+\ds{What if the researchers wanted to run it on a server with multiple GPUs
+(or hundreds of CPU cores?)}
+
 \subsubsection{Longevity Requirements}
 NA -- The product is to be completed by April 2016, and there are no plans to extend that lifetime.
 
@@ -448,6 +473,7 @@ \subsubsection{Supportability Requirements}
 
 \subsubsection{Adaptability Requirements}
 The completed project is expected to run on Fedora and OSx. 
+\ds{Why only those?}
 
 % ----------------------------- Sub Section ----------------------------- %
 \subsection{Security Requirements}\label{ReqType_Security} % Rob
@@ -535,15 +561,24 @@ \subsubsection{Products That Can Be Copied}
 \subsection{New Problems}\label{SubSec_NewProbs} % Stuart
 \subsubsection{Effects on the Current Environment}
 The new product will be designed as an opt-in addition to the existing product. That is, unless manually changed by the user, the program will execute identically as before, running on the CPU. The motivation for this is to ensure compatibility, as the programming environment for GP-GPU programming is restricted to certain hardware. The current environment will not be affected by the changes unless the user specifically decides to use them.
+\ds{You are describing design decisions, not effects on the current environment}
 
 \subsubsection{Effects on the Installed Systems}
 Requirement \ref{Req_EasyChange} specifies the importance of creating a simple interface for the user to enable the changes in the new system, or revert to the previous one. Changes to the code will be isolated, and only used when they are manually enabled.
+\ds{Again you are talking about design. Here you should be detailing what your
+how your product interfaces with the existing system. Are there any potential
+conflicts that would need to be solved (i.e. by your design decision)?}
 
 \subsubsection{Potential User Problems}
 Due to the separation of the changes and the existing product, users will not negatively respond to the changes, indeed they won't even notice them unless actively looking. To use the new product's features, users will enable them and then execute the program in an identical manner to how the existing software works (requirement \ref{Req_EasyChange}).
+\ds{You are again making design decisions instead of detailing potential problems
+to be solved by those decisions}
 
 \subsubsection{Limitations of the Anticipated Implementation Environment That May Inhibit the New Product}
-To run the GP-GPU computations, specific hardware is required (recent NVIDIA graphics card).
+To run the GP-GPU computations, specific hardware is required
+\ds{You should stop here, unless you explained (in the constraints section)
+why you need an NVIDIA card. Also, what is ``recent"?}
+(recent NVIDIA graphics card).
 
 \subsubsection{Follow-Up Problems}
 There are a number of potential situations that could lead to the product failing. We are confident that we will be able to succeed, however we realize that there is a possibility of failure, and have outlined the potential causes below.
@@ -588,7 +623,8 @@ \subsection{Risks} % Rob
 \begin{itemize}
 	\item Excessive schedule pressure
 	\item Technical/Resource limitations
-	\item Inadequate measurements
+	\item Inadequate measurements 
+	\ds{What do you mean by this?}
 	\item Optimistic time constraints
 \end{itemize}
 

README.md

@@ -1,15 +1,94 @@
-# Porting GEANT-4 Particle Simulation to GPU
-
-GEANT-4 is a widely-used simulation program used to simulate particle
-interactions. There are currently several members of McMaster's Engineering
-Physics department that use the program, and are being limited by the
-performance of the software. This means that they cannot simulate particle
-interactions that take place over the course of minutes (or even seconds), and
-they also can't simulate large numbers of particles.
-
-Increasing the runtime of the simulation or the number of particles would
-greatly increase the accuracy of their results, allowing the researchers to
-understand the systems they're modeling better. This is especially true when
-modeling complex systems, such as McMaster's nuclear reactor. Depending upon the
-level of success of the project, the solution could potentially benefit groups
-that use GEANT-4 outside of McMaster as well.
+Porting G4-STORK particle simulation software to GPU
+==========
+
+GEANT-4 is a widely-used software toolkit used to simulate particle
+interactions. Several members of McMaster's Engineering Physics department 
+have created G4-STORK, a program that uses the GEANT-4 toolkit to simulate 
+particle interactions in McMaster's nuclear reactor. Due to the computation 
+time needed to run these simulations, they cannot simulate particle 
+interactions that take place over the course of minutes (or even seconds), or 
+that have a large numbers of particles.
+
+The goal of this project is to port the calculations done by GEANT-4 to a GPU 
+architecture using CUDA. This will significantly increase the performance of 
+the simulations, allowing researchers to use more accurate models of the 
+system.
+
+## Table of Contents
+**[Prerequisites](#prerequisites)**<br>
+**[Installation](#installation)**<br>
+**[Troubleshooting](#troubleshooting)**<br>
+**[FAQ](#FAQ)**<br>
+
+Prerequisites
+==========
+The following operating systems are supported:
+- Mac OS X (tested on 10.11 with Xcode 6)
+- Fedora 20
+
+*Note*: Xcode 7 includes a newer version of the clang compiler that is not yet 
+supported.
+
+To run computations on the GPU with CUDA, a relatively new **NVIDIA GPU** is 
+required.
+
+Installation
+==========
+**Install cmake**<br>
+1. Download cmake 2.8.4 from https://cmake.org/files/v2.8/<br>
+2. Follow the instructions in the readme included with the download
+
+**Install topc-2.5.2**<br>
+1. `cd /path/to/GEANT4-GPU/topc-2.5.2`<br>
+2. `./configure` (installs to `usr/local/include` and `usr/local/src`)<br>
+3. `make install`
+
+**Install marshalgen-1.0**<br>
+1. (Fedora only) `yum install bison flex`<br>
+2. `cd /path/to/GEANT4-GPU/marshalgen-1.0`<br>
+3. `make`
+
+**Install GEANT-4**<br>
+1. (Fedora only) `yum install expat-devel`<br>
+2. `cd /path/to/GEANT4-GPU/geant4.10.01.p02-build`<br>
+3. `cmake -DGEANT4_INSTALL_DATA=ON -DCMAKE_INSTALL_PREFIX=/path/to/GEANT4-GPU/
+geant4.10.01.p02-install /path/to/GEANT4-GPU/geant4.10.01.p02`<br>
+4. `make -jN` where `N` is the number of processors on your computer<br>
+5. `make install`
+
+**Install G4-STORK**<br>
+1. `cd /path/to/GEANT4-GPU/G4STORK/Build`<br>
+2. `source /path/to/GEANT4-GPU/geant4.10.01.p02-install/bin/geant4.sh`<br>
+3. `rm -rf CMakeCache.txt CMakeFiles/`<br>
+4. `cmake -DTOPC_USE=1 -DGeant4_DIR=/path/to/GEANT4-GPU/geant4.10.01.p02-
+install/lib/Geant4.10.00.p02/Geant4Config.cmake ../`<br>
+5. `make -jN` where `N` is the number of processors on your computer
+
+To test that everything installed properly, (TODO: figure out a test).
+
+
+Troubleshooting
+==========
+
+
+FAQ
+==========
+**What is GEANT-4**<br>
+Many physics researchers use GEANT-4 to learn about how particles interact 
+with a specific environment. It is a toolkit (i.e. library) that uses the 
+Monte Carlo model, meaning each particle's properties are calculated 
+independently according to certain probabilities. It runs all those 
+calculations, and provides output.
+
+**What is G4-STORK**<br>
+McMaster's Engineering Physics department created G4-STORK -- a project that 
+leverages GEANT-4 to study the McMaster nuclear reactor. G4-STORK includes the 
+necessary data structures and algorithms specific to the reactor, and also 
+adds CPU parallelization via the MPI model.
+
+**Why will running the simulations on a GPU improve the performance**<br>
+GPU's contain a large amount of cores that can perform calculations much more 
+quickly than a CPU if the problem is well-suited to parallelization. GEANT-4 
+runs relatively simple calculations on millions of particles, and each 
+particle is completely independent of the others. This is exactly that sort of 
+well-suited problem, and stands to see large performance gains.