7.2.2011 Kamil Sedlak

1) Constant fraction discriminator added to the analysis of the 
     optical photon signal. 
  2) Bug fixes in the optical photon simulation.
  3) A few other small improvements.

doc/musrSim.tex

@@ -126,7 +126,8 @@ in the macro file:
 \end{itemize}
 
 By default, the output of the simulation is written out in the subdirectory ``data'' with
-the name ``musr\_RUNNUMBER.root''.
+the name ``musr\_RUNNUMBER.root''.  The default ``data'' directory can be changed by the
+command ``/musr/command rootOutputDirectoryName \emph{dirName}''.
 (Note that the execution of the simulation can be terminated gently by creating a file ``RUNNUMBER.stop'' in the working directory.)
 
 \section{Conventions}
@@ -747,10 +748,72 @@ in order to simulate optical photons:
 	    E.g.\ REFLECTIVITY or EFFICIENCY for a given surface may be assigned this way.
        \end{description}
 
-One has to assign a non-zero EFFICIENCY and a REFLECTIVITY smaller than 1 to a boundary surface
-between the scintillator and sensitive device (e.g.\ an APD).
+\item {\bf /musr/command OPSA \emph{subcommand} \emph{parameters ...}}\\
+       Different commands related to Optical Photon Signal Analysis (OPSA):\\
+       \begin{description}
+	   \item{\bf signalSeparationTime \emph{timeSeparation}} \\
+	        If two subsequent optical photons arrive to the same active detector
+		in time smaller than \emph{timeSeparation}, they will form
+		the same ``optical photon signal''.  Otherwise (i.e.\ if there is no photon
+		detected for time larger than \emph{timeSeparation}) the next arriving photon
+		will start a new ``optical photon signal''.  See the similarity
+		to the command ``/musr/command signalSeparationTime \emph{timeSeparation}''
+		for the deposited energy signals.
+	    \item{\bf OPSAhist \emph{nBins} \emph{min} \emph{max}} \\
+	        Defines ``OPSA'' histograms -- i.e.\ histograms that
+		contain the time distribution of the arival of optical photons.\\
+		\emph{nBins} ... number of bins of the histogram\\
+		\emph{min} ... minimum of the x-axis of the histogram\\
+		\emph{max}... maximum of the x-axis the histogram\\
+	
+		In fact three kinds of histograms are created -- see command
+		``/musr/command OPSA eventsForOPSAhistos \emph{eventID} \emph{detID}''.
+
+	    \item{\bf eventsForOPSAhistos \emph{eventID} \emph{detID}}\\
+	        Defines event number and detector ID, for which histograms of the
+		OPSA will be stored.  If \emph{detID} is set to zero, all detectors will be
+		stored for the given event.
+		
+		The naming convention for the histograms is the following:
+		OPSAhist\_\emph{eventID}\_\emph{detID}\_\emph{n} ,\\ 
+		where \emph{n} is the number of the ``optical photon signal'' in the
+                event \emph{eventID} in the detector \emph{detID}.\\
+		There are other two histograms, namely 
+		``OPSAshape\_\emph{eventID}\_\emph{detID}\_\emph{n}'', which shows
+		the signal from OPSAhist convoluted with the responce function
+		of the optical detection device as e.g.\ G-APD, and 
+		``OPSA\_CFD\_\emph{eventID}\_\emph{detID}\_\emph{n}'', which shows
+		the signal from OPSAshape after the constant fraction discriminator.
+	    \item{\bf pulseShapeArray \emph{pulseShapeFileName}}\\
+	        \emph{pulseShapeFileName} is the name of the file that contains responce 
+		function (pulse shape) of a single cell (single photon) detected by 
+		the photosensitive detector.  The data format is very strict:\\
+		\% ... comments \\
+		first column ...  time in picosecond  (it has to be: 0, 1, 2, ... iPSmax
+                                    where iPSmax is smaller than 10000)\\
+                second column ... amplitude of the APD response function\\
+		{\bf Internally in musrSim, the data read from this file are interpolated to the
+		centers of the bins of the histograms defined by
+		``/musr/command OPSA OPSAhist ''}.
+
+	    \item{\bf CFD \emph{a1} \emph{delay} \emph{timeShiftOffset}}\\
+	    \item{\bf minNrOfDetectedPhotons}\\
+	    \item{\bf photonFractions}\\
+       \end{description}
+
 \end{description}
 
+
+\subsection*{Tips and tricks}
+\begin{itemize}
+   \item  One has to assign a non-zero EFFICIENCY and a REFLECTIVITY smaller than 1 to a boundary surface
+          between the scintillator and sensitive device (e.g.\ an APD).
+   \item  To get a perfectly reflecting surface, one can use REFLECTIVITY=1; EFFICIENCY=0; 
+          \emph{surfaceType}=dielectric\_metal, \emph{surfaceFinish}=polished, \emph{surfaceModel}=unified.
+	  
+\end{itemize}
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \section{Some other parameters}
 %
@@ -760,6 +823,10 @@ between the scintillator and sensitive device (e.g.\ an APD).
 	\emph{nrOfEvents} (int) -- number of events to be simulated.\\
 	(This is a default Geant4 command, which has to be specified in any simulation run).
 
+\item{\bf /musr/command rootOutputDirectoryName \emph{dirName}} \\
+        (default: /musr/command rootOutputDirectoryName data )\\
+        Specify the (sub)directory to which the output file will be written out.
+
 \item{\bf /musr/command logicalVolumeToBeReweighted mu \emph{logicalVolume} \emph{weight} }\\
 	(default: not defined; no reweighting is done unless explicitly requested by this command.) \\
 	Events can be reweighted by this command.  If muon {\bf stops and decays} in the