Merge branch 'master' of https://github.com/studouglas/GEANT4-GPU

Documentation/DesignDoc/DetailedDesign.tex

@@ -79,8 +79,9 @@ \subsection{Revision History}
 \toprule
 \bf Description of Changes & \bf Author & \bf Date\\\midrule
 \arrayrulecolor{lightgray}
-Set up sections and filled out Introduction section & Matthew & 2015-12-15\\\hline
-Added sections for Errors and Key Algorithms & Stuart & 2016-01-08\\
+Set up sections and filled out Introduction section & Matt & 2015-12-15\\\hline
+Added sections for Errors and Key Algorithms & Stuart & 2016-01-08\\\hline
+Created implementation 2 Section & Matt & 2016-04-21\\
 \arrayrulecolor{black}
 \bottomrule
 \end{tabular}
@@ -118,7 +119,9 @@ \subsection{Technologies and Languages}
 \subsection{Notes}
 Geant4 uses its own basic types for standard C++ types (G4int, G4bool, G4double, etc). These types are currently just \texttt{typedefs} to the respective type as defined in the system libraries.\\
 
-The modules G4NeutronHPDataPoint and G4ParticleVector described below are existing modules of Geant4. All methods and state variables are pre-existing, and will be replicated on the GPU. The interface of the modules will not change.
+The modules G4NeutronHPDataPoint and G4ParticleVector described below are existing modules of Geant4. All methods and state variables are pre-existing, and will be replicated on the GPU. The interface of the modules will not change.\\
+
+This document contains two different implementations for G4ParticleVector. Both implementations use the same implementation for G4NeutronHPDataPoint.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ----- NeutronHPDataPoint
 \section{G4NeutronHPDataPoint}
@@ -208,7 +211,7 @@ \subsection{Key Algorithms}
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ----- NeutronHPVector
-\section{G4ParticleVector}
+\section{G4ParticleVector -- Implementation 1}
 
 \subsection{Description}
 This module stores a large vector of data points (G4NeutronHPDataPoint). It includes functions for setting the data points, retrieving them, and calculating information over them (such as the integral).
@@ -388,6 +391,82 @@ \subsection{Key Algorithms}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ---- NeutronHPVector
 
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ----- NeutronHPVector
+\section{G4ParticleVector -- Implementation 2}
+
+\subsection{Description}
+Instead of storing and maintaining everything on the GPU, only functions which are well suited to run on the GPU are implemented. The data vector will
+be stored and maintained on the CPU in this implementation and will be sent to the GPU for processing results.
+
+\subsection{MIS (Module Interface Specification)}
+Note that hyphens in routine names, inputs, outputs, and exceptions are just for linebreaks due to the table size. The actual routine names, inputs, outputs, and exceptions do not have hyphens.
+
+\subsubsection{Access Program Syntax}% ================ Victor
+\begin{longtable}{p{0.28\textwidth}p{0.28\textwidth}p{0.28\textwidth}p{0.14\textwidth}}
+\caption{G4ParticleVector -- access program syntax}\label{Table_NeutronHPVectorInterface}\\
+\toprule
+\bf Routine Name & \bf Input & \bf Output & \bf Exceptions \\\midrule
+\arrayrulecolor{lightgray}
+SetInterpolationManager & const G4InterpolationManager \&  & & \\\hline
+SetInterpolationManager & G4InterpolationManager \&  & & \\\hline
+GetXsecList & G4double, G4int, G4ParticleHPDataPoint*, G4int & &\\\hline
+GetMinIndices\_CUDA & G4ParticleHPDataPoint* , int, double* , int, int* & &\\
+\arrayrulecolor{black}
+\bottomrule
+\end{longtable}
+
+\subsubsection{Access Program Semantics}% ============ Rob
+Note that hyphens in routine names and inputs are just for linebreaks due to the table size. The actual routine names and inputs do not have hyphens.
+
+\begin{longtable}{p{0.25\textwidth}p{0.3\textwidth}p{0.45\textwidth}}
+\caption{G4ParticleVector -- access program semantics}\label{Table_NeutronHPVectorSemantics}\\
+\toprule
+\bf Routine Name & \bf Input & \bf Description \\\midrule
+\arrayrulecolor{lightgray}
+SetInterpolation-Manager & G4Interpolation-Manager\& & sets \texttt{theManager} to the input \\\hline
+GetXsecList & G4double, G4int, G4ParticleHPDataPoint*, G4int & Takes a list of energies and finds their corresponding xSecs\\\hline
+GetMinIndices\_CUDA & G4ParticleHPDataPoint* , int, double* , int, int* & device function used to find the indexes for the query values given\\\hline
+\arrayrulecolor{black}
+\bottomrule
+\end{longtable}
+
+\subsubsection{State Variables}% ================== Matt
+The following variables maintain state for the class, and are all private to the class.
+
+Note that hyphens in variable names and types are just for line breaks due to the table size. The actual variable names and types do not have hyphens.
+
+\begin{table}[h]
+\caption{G4ParticleVector -- state variables}\label{Table_NeutronHPDataPointStateVariables}
+\begin{tabularx}{\textwidth}{p{0.2\textwidth}p{0.2\textwidth}p{0.5\textwidth}}
+\toprule
+\bf Variable & \bf Type & \bf Description\\\midrule
+\arrayrulecolor{lightgray}
+\texttt{theManager} & G4Interpolation-Manager & manages the interpolation schemes, knows how to interpolate data\\\hline
+\texttt{theInt} & G4Neutron-Interpolator & the interpolator for sampling data (may not be linear)\\
+\arrayrulecolor{black}
+\bottomrule
+\end{tabularx}
+\end{table}
+\subsubsection{Environment Variables}% ============== Matt
+There are no environment variables for this module.
+
+\subsubsection{Assumptions}% ==================== Stuart	
+It can be assumed that the module will be initialized before other functions are called.
+
+\subsection{Error Handling}
+The \texttt{Check} method throws a G4HadronicException on error, however it is the only function to do so in the module. In the other functions, erroneous input is not handled explicitly beyond control statement checks that will assume default values for any invalid parameters.
+
+\subsection{Key Algorithms}
+There are a variety of algorithms used in the module. When porting to the GPU, the same algorithms will be modified to run in parallel. In general, this consists of taking array traversals and running the procedures executed sequentially at the same time on different cores of the GPU. 
+
+\subsubsection{GetXsecList}
+GetXsecList takes in an array of energy queries, it then sends that array to the GPU to work on. The GPU divides up the work by having each individual thread on the GPU be responsible for a single energy query. Every thread will look through the data vector independently until it finds the xSec corresponding to its energy value. This will all be happening in parallel. The results found replace the corresponding query energies  
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ---- NeutronHPVector
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ----- Cmake Files
 \section{CMake Files}
 \subsection{Description}\label{Sec_CMakeDesc}
@@ -403,10 +482,10 @@ \subsubsection{Access Program Semantics}% ============ Rob
 \subsubsection{State Variables}% ================== Matt
 \begin{table}[h]
 \caption{CMake Files -- state variables}\label{Table_CMakeStateVariables}
-\begin{tabularx}{\textwidth}{p{0.1\textwidth}p{0.1\textwidth}p{0.7\textwidth}}
+\begin{tabularx}{\textwidth}{p{0.25\textwidth}p{0.1\textwidth}p{0.55\textwidth}}
 \toprule
 \bf Variable & \bf Type & \bf Description\\\midrule
-\texttt{useCuda} & Boolean & if set to true, the makefiles generated by CMake will include directives to compile and link the CUDA code and will execute ported procedures on the GPU. Default is false.\\
+\texttt{GEANT4\_Enable\_CUDA} & Boolean & if set to true, the makefiles generated by CMake will include directives to compile and link the CUDA code and will execute ported procedures on the GPU. Default is false.\\
 \bottomrule
 \end{tabularx}
 \end{table}
@@ -421,10 +500,10 @@ \subsubsection{Assumptions}% ==================== Stuart
 It is assumed the user has CMake installed, as it is required for Geant4.
 
 \subsection{Error Handling}
-If the tries to enable CUDA without compatible hardware, CMake will detect this and output a fatal error message. The user will not be able to enable CUDA unless they have compatible hardware. If the user is using an older version of CMake (before 2.8) that does not support CUDA compilation, a fatal error message will be outputted.
+If user the tries to enable CUDA without compatible hardware, CMake will detect this and output a fatal error message. The user will not be able to enable CUDA unless they have compatible hardware. If the user is using an older version of CMake (before 2.8) that does not support CUDA compilation, a fatal error message will be outputted.
 
 \subsection{Key Algorithms}
-CMake is the existing build system for generating make files for the project. As such, there are no key algorithms to document.
+When GEANT4\_Enable\_CUDA is set to true CMake will configure a header file which will indicate if Geant4 needs to include the CUDA files or not. This file then gets moved to the include directory where G4ParticleHPVector.hh can see it and include it.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ---- Cmake Files
 

Documentation/DesignDoc/SystemArchitecture.tex

@@ -218,7 +218,9 @@ \subsection{GPU Integration Approach}\label{Sec_IntegrationApproach}
 
 In all options except 1 and 2, a function call to one of the functions of a ported class will be received by the existing C++ class, which will then either execute the existing code if that function has not been ported or if GPU computation is disabled, or will call the corresponding function from the CUDA file.
 
-Option 5 was chosen due to its ability to divide work easily, its compatibility with the current codebase, and the memory advantages over option 4.
+Option 5 was chosen due to its ability to divide work easily, its compatibility with the current codebase, and the memory advantages over option 4. 
+
+Option 3 was also implemented after performance testing showed that option 5 did not provide any significant speed ups.
 
 \subsection{G4ParticleVector}\label{subsec_G4ParticleVector} % rob
 As was explained in the preceding subsection, the problem has been decomposed to that of only integrating specific functions from given modules with the CUDA technology. With that said, a decision needed to be made as for which class and which functions within that class to integrate.