diff --git a/doc/musrSim.pdf b/doc/musrSim.pdf index 1067b5a..d4231c7 100644 Binary files a/doc/musrSim.pdf and b/doc/musrSim.pdf differ diff --git a/doc/musrSim.tex b/doc/musrSim.tex index 7c4cf9b..9e1203c 100644 --- a/doc/musrSim.tex +++ b/doc/musrSim.tex @@ -47,14 +47,14 @@ Geant4}. The root output variables are also described. \section{Scope of the musrSim program} The program ``musrSim'' is a relatively general program that can be used to simulate the response of a $\mu$SR~\cite{Blundel:1999} instruments (detectors) to muons and their decay particles -(electrons, positrons and gammas), optionaly including ``optical photons''. +(electrons, positrons and gammas), optionally including ``optical photons''. Even though musrSim is tailored to the needs of the $\mu$SR technique~\cite{shirokaGeant}, it has been used also in the studies of beam-line elements like spin rotators, as well as in the detector development studies without any muons involved, e.g.\ to test the response of an APD-based -scintillator counters to the irradiation of Sr radioactive source~\cite{AlexeyTestAPD}. -It should be streitforward to apply musrSim also to the low energy particle-physics +scintillator counters to the irradiation of Sr radioactive source~\cite{FirstExperience}. +It should be straightforward to apply musrSim also to the low energy particle-physics experiments with muons. The program is based on the Geant4~\cite{geant} and Root~\cite{root} libraries. @@ -95,7 +95,7 @@ In our view, the main advantages of musrSim are: \item Possibility to use musrSim easily for calculating muon stopping profile (also in e.g.\ sample cells) or in developments of detector components (e.g.\ light propagation in the scintillator of a positron/muon counter - and the subsequent light collectin in a photomultiplier tube or APD). + and the subsequent light collection in a photomultiplier tube or APD). \end{itemize} % On the other hand, there are also some drawbacks and limitations: @@ -129,7 +129,7 @@ Once Geant4 has been successfully installed and some of the default Geant4 examp has been run, the musrSim installation package can be downloaded from the web page http://lmu.web.psi.ch/simulation/index.html. Usually the ``env.sh'' script has to be run to set-up the environment variables -appropriatelly before the musrSim (and/or any other Geant4 application) can be compiled +appropriately before the musrSim (and/or any other Geant4 application) can be compiled and run. The simulation is started by executing: @@ -159,7 +159,7 @@ in the macro file: By default, the output of the simulation is written out in the subdirectory ``data'' with the name ``musr\_RUNNUMBER.root''. The default ``data'' subdirectory can be changed -(see Chapter~\ref{sec:otherParameters}). The simulated data are storred in a Root tree, +(see Chapter~\ref{sec:otherParameters}). The simulated data are stored in a Root tree, which is some kind of a table with many variables for every simulated event, inside the musr\_RUNNUMBER.root file. @@ -195,7 +195,7 @@ are summarised in table~\ref{tab:units}. Momentum && MeV/c\\ Magnetic field && tesla \\ Electric field && keV/mm \\ - Anlgel && degree \\ + Angle && degree \\ \hline \end{tabular} \caption{The default units of musrSim.} @@ -206,13 +206,13 @@ are summarised in table~\ref{tab:units}. \begin{itemize} \item Visualise your instrument geometry during its construction. \item Check the output file for error messages, especially for volume overlaps. - \item Note the the dimensions in volume definitions are often half-lenghts, not - the lenghts (e.g.\ half-lengths of the box edges). + \item Note the the dimensions in volume definitions are often half-lengths, not + the lengths (e.g.\ half-lengths of the box edges). \item The order of some commands in macro file matters -- e.g.\ one has to define a mother volume before the daughter volume, etc. - \item Threre are some special volume names, namely \emph{World}, + \item There are some special volume names, namely \emph{World}, \emph{Target} (same as \emph{target}), \emph{M0}, \emph{M1}, \emph{M2} and - volumes starging with keywords \emph{Shield} (same as \emph{shield}), and + volumes starting with keywords \emph{Shield} (same as \emph{shield}), and volumes containing string \emph{save}. All these volume influence the behaviour of the simulation, so understand how they act (see different chapters of this manual) before you use them. @@ -222,7 +222,7 @@ are summarised in table~\ref{tab:units}. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Detector construction} -The user must first define the instrument geometry in the macro file. It should be realively +The user must first define the instrument geometry in the macro file. It should be relatively easy to understand how this is done from the example macro files distributed with musrSim program. @@ -232,11 +232,41 @@ The ID volume numbers are later on used also in the musrSimAna program, when som of a volume becomes necessary (i.e.\ volumes are described by \emph{idNumber} rather than by their \emph{name} command later on). -Another crutial parameter in ``/musr/command construct'' command +Another crucial parameter in ``/musr/command construct'' command is \emph{sensitiveClass}, which defines whether the volume is sensitive (i.e.\ a signal can be detected in the volume) or not (i.e.\ the volume is just a dead material influencing the penetrating particles but not detecting them). +There are some special kind of volumes, which are defined by the name (or part of the name). +The user can (but does not have) to use them. +The first of them is the volume named ``Target'' (or ``target''). It is expected, that +this is the sample, and the quantities {\tt muTargetTime, muTargetPolX, muTargetPolY, muTargetPolZ, +muTargetMomX, muTargetMomY, muTargetMomZ}, +will be saved when a muon enters this volumes for the first time in a given event. + +The second special kind of volumes are the volumes named ``M0'', ``M1'' and ``M3'' (or ``m0'', +``m1'' and ``m3''). Typically these volumes can be trigger detectors. +The quantities {\tt muM0Time, muM0PolX, muM0PolY, muM0PolZ} +will be saved when a muon enters the volume called ``M0'' (or ``m0'') for the first time +(similarly for ``M1'' and ``M2''). +Note that it is not expected that {\tt muM0Time} should be used in the analysis of the +simulation -- one should use the {\tt det\_time\_start} quantity, which corresponds +to the measured time in the experiment. + +The third class of special volumes has names starting with the string ``save''. +Their purpose in the simulation is usually to check positions +and momenta of particles at some position of the detector, even if the particle does not deposit any energy in +the given ``save'' volume. Save volumes can therefore be made of vacuum. +See section\ref{sec:rootVariables} for further details on what is saved in the Root tree. + +The last special class of volumes has names starting with the string ``kill'', +``shield'' or ``Shield''. +If a particle enters the ``kill \ldots'' volume, it is removed from further simulation. +The same is true for the ``shield \ldots'' or ``Shield \ldots'' volumes for +any particle apart for a muon. +The motivation for this kind of volumes was to speed up the simulation by removing tracks +that are unlikely to hit any detector. The ``kill'', ``shield'' and ``Shield'' volumes should be use with +care. \begin{description} @@ -330,7 +360,6 @@ is just a dead material influencing the penetrating particles but not detecting The variables \emph{gammaCut, electronCut} and \emph{positronCut} are given in mm. \end{description} -{\huge !!! EDIT: !!! Three special volumes ``Target, M0, M1 and M2''.} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Electric and magnetic fields} @@ -429,7 +458,7 @@ is just a dead material influencing the penetrating particles but not detecting after the ``0'' character in the field map file.\\ It is expected that the field map is defined in the full volume of the field. Sometimes (due to the symmetry of the field), it is enough to define the - field in just one octant of the Kartesian coorinate system (e.g. for positive + field in just one octant of the Cartesian coordinate system (e.g. for positive $x$, $y$ and $z$). In such cases, the user can specify this in the field map file using the keyword ``symmetryType \emph{number}'', where the \emph{number} specifies how the field should be extrapolated to other octants. @@ -560,7 +589,7 @@ However, later on we implemented a possibility to change the direction of the in to a random vector by the command ``/gun/direction''. It now works like this: the primary particles are first generated using all parameters of /gun/* commands as if the beam went along the $z$-axis, and just in the last moment before Geant4 starts -to track them, they are (optionaly) rotated to the direction defined by the /gun/direction command. +to track them, they are (optionally) rotated to the direction defined by the /gun/direction command. This way the smearing of the vertex as well as beam tilt/pitch are propagated through the rotation. \begin{description} @@ -571,7 +600,7 @@ This way the smearing of the vertex as well as beam tilt/pitch are propagated th \item{\bf /gun/meanarrivaltime \emph{meanArrivalTime}}\\ (default: /gun/meanarrivaltime 33.33333 microsecond)\\ - Set mean arrival time difference between two subsequent muons (at continuos beam). + Set mean arrival time difference between two subsequent muons (at continuous beam). The output variable ``timeToNextEvent'' is subsequently randomly generated using the value of \emph{meanArrivalTime} and filled into the Root tree. @@ -751,10 +780,10 @@ This way the smearing of the vertex as well as beam tilt/pitch are propagated th \item{\bf /gun/turtleInterpretAxes \emph{axesWithSign}}\\ Normally it is expected that the coordinates in TURTLE are x, xprime, y and yprime. - One can specify whether the x and y axes of the position in TURTLE should be interpretted differently. + One can specify whether the x and y axes of the position in TURTLE should be interpreted differently. The following options are supported for \emph{axesWithSign}: x-y, -xy, -x-y, yx, y-x, -yx, -y-x .\\ Example: the option y-x means that first four coordinates in the TURTLE input file - are interpreded as y, yprime, -x, -xprime. + are interpreted as y, yprime, -x, -xprime. \item{\bf /gun/turtleMomentumBite \emph{turtleMomentumP0} \emph{turtleSmearingFactor} \emph{dummy} }\\ Modify the smearing of the momentum bite specified in the TURTLE input file. @@ -799,10 +828,10 @@ This way the smearing of the vertex as well as beam tilt/pitch are propagated th %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Optical photons} \label{sec:opticalPhotons} -Normaly the simulation of ``detected signal'' stops at the level of the deposited energy in -a sensitive volume (e.g.\ in a scintilator tile). However, in some special cases, one would +Normally the simulation of ``detected signal'' stops at the level of the deposited energy in +a sensitive volume (e.g.\ in a scintillator tile). However, in some special cases, one would like to know how the light is propagated through the scintillators. In such case simulation -of optical photons is possible. Note that the optical photon in Geant are treaded as a class +of optical photons is possible. Note that the optical photon in Geant are treated as a class of particles distinct from higher energy gamma particles -- and there is no smooth transition between the two. Some additional material properties of an active detector and of the detector surface have to be defined for optical photons. @@ -835,11 +864,11 @@ in order to simulate optical photons: FASTTIMECONSTANT, SLOWTIMECONSTANT, and YIELDRATIO. See other \emph{property} keywords in chapter ``Optical Photon Processes'' in~\cite{geantUserManual}.\\ \begin{description} - \item{\bf SCINTILLATIONYIELD} ... nr. of photons per 1\,MeV of deposited energy. + \item{\bf SCINTILLATIONYIELD} ... no. of photons per 1\,MeV of deposited energy. \item{\bf RESOLUTIONSCALE} ... intrinsic resolution -- normally 1, larger than 1 for crystals with impurities, smaller than 1 when Fano factor plays a role. \item{\bf YIELDRATIO} ... relative strength of the fast component as a fraction - of total scintillation yeald. + of total scintillation yield. \end{description} \item {\bf /musr/command setMaterialPropertiesTable \emph{MPT\_name} \emph{material\_name}} \\ @@ -873,7 +902,7 @@ in order to simulate optical photons: 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.\\ + contain the time distribution of the arrival 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\\ @@ -892,20 +921,20 @@ in order to simulate optical photons: 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 + the signal from OPSAhist convoluted with the response 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 + \emph{pulseShapeFileName} is the name of the file that contains response 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 + first column ... time in picoseconds (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 + centres of the bins of the histograms defined by ``/musr/command OPSA OPSAhist ''}. \item{\bf CFD \emph{a1} \emph{delay} \emph{timeShiftOffset}}\\ @@ -1057,6 +1086,7 @@ in order to simulate optical photons: \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Output root tree variables} +\label{sec:rootVariables} The value of -999 or -1000 indicates that the given variable could not be filled (was undefined in a given event). For example if the variable ``muTargetTime'' is set to -1000 it means that the initial muon missed the sample, @@ -1097,7 +1127,8 @@ The list of variables that can be stored in the Root tree: \item{\bf muDecayPosX, muDecayPosY, muDecayPosZ} (Double\_t) -- the position where the muon stopped and decayed (in mm). \item{\bf muDecayPolX, muDecayPolY, muDecayPolZ} (Double\_t) -- polarisation of the muon when it stopped and decayed. \item{\bf muTargetTime} (Double\_t) -- time at which the muon entered the volume whose name starts by ``target'' -- usually the sample (in $\mu$s). -\item{\bf muTargetPolX, muTargetPolY, muTargetPolZ} (Double\_t) -- polarisation of the muon when it entered the volume whose name starts with ``target'' -- usually the sample. +\item{\bf muTargetPolX, muTargetPolY, muTargetPolZ} (Double\_t) -- polarisation of the muon when it entered the volume whose name is ``target'' -- usually the sample. +\item{\bf muTargetMomX, muTargetMomY, muTargetMomZ} (Double\_t) -- momentum of the muon when it entered the volume whose name is ``target'' -- usually the sample. \item{\bf muM0Time} (Double\_t) -- time at which the muon entered the detector called ``M0'' or ``m0'' (in $\mu$s). \item{\bf muM0PolX, muM0PolY, muM0PolZ} (Double\_t) -- polarisation of the muon when it entered the detector called ``M0'' or ``m0''. \item{\bf muM1Time} (Double\_t) -- time at which the muon entered the detector called ``M1'' or ``m1'' (in $\mu$s). @@ -1181,7 +1212,7 @@ The list of variables that can be stored in the Root tree: -- times, when the the first and last photons contributing to the given signal were detected (odet\_timeFirst and odet\_timeLast). \item{\bf odet\_timeA[odet\_n], odet\_timeB[odet\_n]} (array of Double\_t) -- time, when the $n^{th}$ photon was detected, where $n$ for \emph{odet\_timeA[i]} is given as \emph{OPSA\_fracA} - multiplied by \emph{odet\_nPhot[i]}. Similary for \emph{odet\_timeB[i]}. + multiplied by \emph{odet\_nPhot[i]}. Similarly for \emph{odet\_timeB[i]}. The variables \emph{OPSA\_fracA} and \emph{OPSA\_fracB} are defined by the ``/musr/command OPSA photonFractions'' command (see chapter~\ref{sec:opticalPhotons}). \item{\bf odet\_timeC[odet\_n]} (array of Double\_t) @@ -1201,7 +1232,7 @@ The list of variables that can be stored in the Root tree: the given ``save'' volume. Save volumes can therefore be made of vacuum. \item{\bf save\_detID[save\_n]} (array of Int\_t) -- ID number of the save volume. \item{\bf save\_particleID[save\_n]} (array of Int\_t) -- particle ID of the particle that entered the save volume. -\item{\bf save\_time[save\_n]} (array of Double\_t) -- time when the particle enetered in the volume (in $\mu$s). +\item{\bf save\_time[save\_n]} (array of Double\_t) -- time when the particle entered in the volume (in $\mu$s). \item{\bf save\_x[save\_n], save\_y[save\_n], save\_z[save\_n]} (array of Double\_t) -- position of the particle where it entered the save volume (``GetPreStepPoint()'') (in mm). \item{\bf save\_px[save\_n], save\_py[save\_n], save\_pz[save\_n]} (array of Double\_t) -- momentum of the particle when it @@ -1290,9 +1321,9 @@ scintillator tiles.} \end{figure} % illustrates a simple geometry made of an electron source and two blocks -of scintilator tiles with the dimensions of $3 \times 3 \times 2\,$mm, +of scintillator tiles with the dimensions of $3 \times 3 \times 2\,$mm, which is defined in the macro file ``101.mac''. -The primary particles are electrons with the energy of 2.15\,MeV shooted +The primary particles are electrons with the energy of 2.15\,MeV shot into the first scintillator. There the electron can be scattered, and therefore it may or may not hit the second scintillator. We have used the command\\[2ex] {\tt /musr/command storeOnlyEventsWithHitInDetID 11}\\[2ex] @@ -1337,7 +1368,7 @@ The data for the strontium and yttrium decay are taken from the Geant4 data files, namely\\ {\tt /home/install/data\_geant4.9.4/RadioactiveDecay3.3/z38.a90}~~~~ and\\ {\tt /home/install/data\_geant4.9.4/RadioactiveDecay3.3/z39.a90}. \\ -There is, however, one problem in musrSim -- it has to handle times with picoseond precission, +There is, however, one problem in musrSim -- it has to handle times with picoseond precision, and the \emph{double} precision used in the c{\tt ++} program is then not enough to deal with the $^{90}$Sr decay time of 29 years. For this reason, one has to modify the decay times in the two data files, i.e.\ @@ -1362,7 +1393,7 @@ of events hits the second counter, and is written out to the output file. (In any case -- the events in which electron does not enter any counter are simulated in a much shorter time than the ``interesting'' events.) -The example {\tt 102.mac} is based on the results published in~\cite{kkkkk}. +The example {\tt 102.mac} is based on the results published in~\cite{FirstExperience}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Example 3 -- Simulation of the light transport (103.mac)} This example is similar to example~1, and extended by the simulation of light (``optical @@ -1370,7 +1401,7 @@ photons''). The light simulation slows down the execution of musrSim dramatical The simulation of light is a new feature in musrSim, and it is being tested. Once this is finished, we will improve this example. However, it seems to be running fine -in its current implementation, so you can start using it. A lot of usefull information +in its current implementation, so you can start using it. A lot of useful information about the optical photons is given in chapter ``Optical Photon Processes'' in the Geant4 User Manual~\cite{geantUserManual}.\\ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1378,10 +1409,10 @@ the Geant4 User Manual~\cite{geantUserManual}.\\ % The General Purpose Decay-Channel Spectrometer (GPD) instrument~\cite{GPD} at PSI, more or less as implemented in reality in the year 2010, is exemplified in -run {\tt 201.mac}. GPD instrument is optimised for the measurements of pressuarised samples +run {\tt 201.mac}. GPD instrument is optimised for the measurements of pressured samples in a special pressure cells. The detector system is relatively simple -- it consist of a rectangular muon counter (10x10x2\,mm), -two backward positron counters, three forward positron counters, cylidrical sample in a cylindrical +two backward positron counters, three forward positron counters, cylindrical sample in a cylindrical sample holder, two lead collimators, one copper collimator, GPD magnet, and some additional ``dead'' material. The GPD geometry is illustrated in Fig.~\ref{fig:vis_201_1}-\ref{fig:vis_201_4}, where some of the elements present in the simulation (beampipe, magnet, aluminium profiles) are not displayed @@ -1482,8 +1513,9 @@ The results of this GPD simulation are described in the \emph{musrSimAna} manual %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Conclusions} -The ... -in~\cite{Aktas:2004px}. +Please let us know your comments and suggestions for further improvement/development of the +musrSim program. + \section{Appendix A: Steering file for the simulation} \begin{verbatim} @@ -1499,9 +1531,6 @@ in~\cite{Aktas:2004px}. \bibitem{Blundel:1999} S.J.~Blundel, Contemp. Phys. 40 (1999) 175. -\bibitem{AlexeyTestAPD} A.~Stoykov {\it et al.}, ``First experience with G-APDs in $\mu$SR instrumentation'', - NDIP08, to be published in Nucl. Instrum. Meth. A. - \bibitem{geant} S.~Agostinelli {\it et al.}, Nucl. Instr. and Meth. A 506 (2003) 250.\\ %-303. \\ J.~Allison, et al., IEEE Trans. Nucl.\ Sci.\ 53 (2006) 270. %-278. \bibitem{root} R.~Brun, F.~Rademakers ``ROOT - An Object Oriented Data Analysis Framework'', @@ -1520,18 +1549,16 @@ http://pc532.psi.ch/turtcomp.htm T.~Shiroka {\it et al.} ``GEANT4 as a simulation framework in muSR'', Physica {\bf B~404}, (2009) 966-969 % -%\cite{Aktas:2004px} -\bibitem{Aktas:2004px} -A.~Aktas {\it et al.} [H1 Collaboration], -%``Measurement of dijet production at low Q**2 at HERA,'' -Submitted to Eur.\,Phys.\,J.\,{\bf C}, [hep-ex/0401010]. -%%CITATION = HEP-EX 0401010;%% \bibitem{GPD} http://lmu.web.psi.ch/facilities/gpd/gpd.html \bibitem{musrSimAna} -K.Sedlak, ``Manual of musrSimAna''. +K.~Sedlak, ``Manual of musrSimAna''. + +\bibitem{FirstExperience} +A.~Stoykov {\it et al.} ``First experience with G-APD in $\mu$SR instrumentation'', +Nucl. Inst. and Meth. in Phys. Res. A {\bf 610} (2009), 374-377. \end{thebibliography} diff --git a/musrSim.cc b/musrSim.cc index df16aaa..ee559ea 100644 --- a/musrSim.cc +++ b/musrSim.cc @@ -40,7 +40,8 @@ int main(int argc,char** argv) { XInitThreads(); - + G4cout<<"\n\n\n*************************************************************"<