diff --git a/doc/dis04.cls b/doc/dis04.cls index 248db15..1d3415f 100644 --- a/doc/dis04.cls +++ b/doc/dis04.cls @@ -226,7 +226,8 @@ Internal PSI draft\hfill \global\let\and\relax } % -\def\title#1{\gdef\@title{\uppercase{#1}}} +%cks\def\title#1{\gdef\@title{\uppercase{#1}}} +\def\title#1{\gdef\@title{\Large{#1}}} \def\@title{\@latex@error{No \expand\title given}\@ehc} %% \def\@maketitle{% @@ -245,7 +246,8 @@ Internal PSI draft\hfill % \def\@aabuffer{} \def\author #1{\expandafter\def\expandafter\@aabuffer\expandafter - {\@aabuffer\small\rm\uppercase{#1}\relax\par + {\@aabuffer\rm #1\relax\par +%cks {\@aabuffer\small\rm\uppercase{#1}\relax\par \vspace*{2pt}}}%\vspace{0.75em} \def\address#1{\expandafter\def\expandafter\@aabuffer\expandafter {\@aabuffer\small\it #1\relax\par diff --git a/doc/musrSim.pdf b/doc/musrSim.pdf index 61f01df..7f285b1 100644 Binary files a/doc/musrSim.pdf and b/doc/musrSim.pdf differ diff --git a/doc/musrSim.tex b/doc/musrSim.tex index 9e9b896..ed5cff7 100644 --- a/doc/musrSim.tex +++ b/doc/musrSim.tex @@ -22,8 +22,10 @@ %\title{GEANT Simulation Program for the %$\mathbf{\mu}$SR Instruments} -\author{Kamil Sedl\'ak and Toni Shiroka PSI} +\author{Kamil Sedl\'ak$^1$, Toni Shiroka$^1$, Zaher Salman$^1$, Tom Lancaster$^2$, Thomas Prokscha$^1$, Taofiq Paraiso$^1$} +\address{{$^1$ Laboratory for Muon Spin Spectroscopy, Paul Scherrer Institut, CH-5232 Villigen PSI, Switzerland}\\ +$^2$ Clarendon Laboratory, Department of Physics, Oxford University, Parks Road, Oxford OX1 3PU, UK} %\address{{\rm (on behalf of the H1 collaboration)}\\ %Institute of Physics AS\,CR\\ %%Academy of Sciences of the Czech Republic @@ -33,191 +35,93 @@ \maketitle \abstracts{ -The program ``musrSim'' is a simulation program based on Geant4 +``musrSim'' is a simulation program based on Geant4, optimised for the $\mu$SR instruments. This document describes some of the commands used in the user macros of the simulation program for the $\mu$SR instruments based on the {\sc 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} instruments (detectors) to muons and their decay particles +(electrons, positrons and gammas). Even though musrSim is tailored to the needs of +the $\mu$SR technique~\cite{shirokaGeant}, it has been used also 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}. -\section{Initial muon parameters} +The program is based on the Geant4~\cite{Geant} and Root~\cite{Root} libraries. +Geant4 is Monte Carlo toolkit used (not only) in particle physics to simulate +the passage of particles through the detectors. +Root is an analysis tool that allows to manipulate and analyse the simulated data, +namely to plot histograms and other graphical output. -\begin{description} -\item{\bf /gun/vertex \emph{x0} \emph{y0} \emph{z0} \emph{unit}}\\ - (default: /gun/vertex 0 0 -100 mm) \\ - Set mean values of the $x$, $y$ and $z$ coordinates of the generated particles (muons). - The smearing around these mean values instead is set by /gun/vertexsigma and - restricted by /gun/vertexboundary (see below).\\ - (Applicable also to TURTLE input). +The aim of the musrSim is to provide an easy-to-use simulation program, which does +not require a deep knowledge of Geant4 in order to simulate a ($\mu$SR) detector. +In our view, the main advantages of musrSim are: +\begin{itemize} + \item Simple way how to define or modify the instrument geometry. + \item Limited (ideally no) need to modify and/or recompile the source code. + \item Implementation of the $\mu$SR-specific classes (muon spin rotation + in magnetic fields, muonium formation and decay, ...). + \item Possibility to read in the output files of the TURTLE~\cite{turle} + program for the beam-line simulation. + \item Simple way how to define (overlapping) electromagnetic fields. + \item Output in the Root tree. +\end{itemize} +% +On the other hand, there are also some drawbacks and limitations: +\begin{itemize} + \item The user has to have an installation of Geant4 and Root before installing musrSim. + \item It is supposed the user will analyse the data with Root, therefore + Root has to be installed and some knowledge of it is needed. + Even though is relatively easy to simulate a $\mu$SR instrument, + and to create the output Root file without even knowing the c++ + programming language, some c++ programming is needed to + analyse the simulation output and to plot graphs. + \item At present time the program does not simulate any muon-spin related + physics processes happening in the sample, except for the muon + spin rotation. + \item The simulation of one event takes much more time than the measurement + of a real event. The simulation time depends on the + complexity of the instrument geometry and on the presence of + electromagnetic fields. To simulate one million of muons + in the case of the PSI high-field instrument took about 10 hours + of a computer time of a desktop PC. +\end{itemize} -\item{\bf /gun/vertexsigma \emph{xSigma} \emph{ySigma} \emph{zSigma} \emph{unit}}\\ - (default: /gun/vertexsigma 0 0 0 mm) \\ - If {\it xSigma} $>0$ ... set $\sigma$, i.e. the standard deviation (RMS), of the $x$ coordinate - of the generated particles (muons) to $\sigma=xSigma$. The $x$ coordinate of the initial - muon is then generated according to the Gaussian distribution with the mean value of $x0$ - and the standard deviation of {\it xSigma}. \\ - If {\it xSigma} $<0$ ... the $x$ coordinate of the initial - muon is generated {\bf uniformly} in the interval of ($x0-$ {\it xSigma}, $x0+$ {\it xSigma}).\\ - If {\it xSigma} $= 0$ ... no smearing on the $x$ coordinate is applied.\\ - Similar is true for {\it ySigma} and {\it zSigma}. \\ - (Ignored by the TURTLE input). +%============================================================================================= +\section{How to install and run musrSim} +To install and run musrSim, one has to install Geant4 and Root first. +The present version of musrSim has been tested with Geant version 4.9.1, patch no.~3 +and Root version 5.20.00. -\item{\bf /gun/vertexboundary \emph{R\_max} \emph{z\_min} \emph{z\_max} \emph{unit}}\\ - Set maximum allowed radius, and minimum and maximum z coordinate of the generated particles (muons). - This command might be useful especially if the user wants to restrict the - area, in which initial particles are created, e.g.\ to force the initial muons - to be created inside the beam pipe. +The musrSim installation package can be downloaded from the web page http://lmu.web.psi.ch/simulation/index.html. +Once compiled, the program can be executed by \emph{``musrSim NNN.mac''}, where NNN.mac is a ``macro file'' +containing the information about the instrument setup. The string NNN represents the integer run number. - If the particles (muons) are read in from an external TURTLE file, - only the restriction on the maximum radius \emph{R\_max} - is applied on the initial particles, while \emph{z\_min} and \emph{z\_max} are ignored. +In order to simulate a new instrument, the user has to define the following blocks of information +in the macro file: +% +\begin{itemize} + \item Define the geometry (the so-called ``volumes'') of the new instrument. + Note that in Geant4 volumes can be included inside other volumes + (a ``daughter'' volume is positioned inside the ``mother'' volume), + and it is therefore necessary to distinguish between the global (world) + coordinates and the coordinates of the daughter volumes (local coordinates). + It is not allowed to overlap any two different volumes partially. + \item Define the electric and magnetic fields. + \item Define physics processes relevant for your case. + \item Define the initial muon parameters (more generally -- initial particle parameters). + \item Define some other parameters influencing the execution of the simulation. + \item Define which variables should be written out to the output Root tree. + \item In case it is required to visualise the geometry, define the visualisation attributes. +\end{itemize} -\item{\bf /gun/kenergy \emph{kineticEnergy} \emph{unit}}\\ - Set the mean kinetic energy of the initial particles (muons).\\ - (Ignored by the TURTLE input). +By default, the output of the simulation is written out in the subdirectory ``data'' with +the name ``musr\_NNN.root''. -\item{\bf /gun/momentum \emph{momentum} \emph{unit}}\\ - Set the mean momentum of the initial particles (muons).\\ - (Ignored by the TURTLE input). - -\item{\bf /gun/momentumsmearing \emph{momentumSigma} \emph{unit}}\\ - Set $\sigma$, i.e. the standard deviation (RMS), of the momentum spread, which - is applied randomly to each generated initial particle (muon). It is the magnitude - of the momentum, which is smeared. \\ - (Ignored by the TURTLE input. However, - a similar command ``/gun/turtleMomentumBite'' can be used for the TURTLE input file.) - -\item{\bf /gun/momentumboundary \emph{p\_min} \emph{p\_max} \emph{dummy} \emph{unit}}\\ - Set a boundary for the minimum and maximum momentum of the initial particles (muons). - The third argument \emph{dummy} is ignored.\\ - (Presently ignored by the TURTLE input). - -\item{\bf /gun/tilt \emph{xangle0} \emph{yangle0} \emph{dummy} \emph{unit}}\\ - The ``beam tilt'' is understood as a constant angle tilt that is applied to - all initial particles (muons) regardless on their distance from the centre of the beam.\\ - (Applicable also to TURTLE input). - -\item{\bf /gun/tiltsigma \emph{xangleSigma} \emph{yangleSigma} \emph{dummy} \emph{unit}}\\ - Gaussian smearing of the tilt angle.\\ - (Presently ignored by the TURTLE input). - -\item{\bf /gun/pitch \emph{pitch} \emph{unit}}\\ - The ``beam pitch'' is understood as a variable angle applied to the initial particles - (muons), which is directly proportional to the distance from the beam axis. - The particles closer to the beam axis become smaller pitch than particles further away - from the beam axis. - The angle given as \emph{pitch} will be applied to a particle generated 1\,mm away from the - beam centre, i.e. the particle generated 7\,mm away from the beam axis will be assigned - the angle of $7\cdot pitch$. - The pitch allows the user to focus or defocus the initial particle - beam. Particles will be focused for positive pitch and defocused for the negative pitch.\\ - (Applicable also to TURTLE input). - -\item{\bf /gun/muonPolarizVector \emph{xpolaris} \emph{ypolaris} \emph{zpolaris}}\\ - Set polarisation of the initial particle (muon) in a form of a vector - $P=(xpolaris,ypolaris,zpolaris)$. The polarisation vector does not have to be normalised, - the normalisation will be done internally by the program. - However note that if the magnitude of P is set to less than 1e-8, the user can - achieve an unpolarised muon beam. See the source code of musrPrimaryGeneratorAction.cc - if you need to use unpolarised beam by this parameter, because there is some trick - based on the magnitude of P.\\ - (Applicable also to TURTLE input). - -\item{\bf /gun/muonPolarizFraction \emph{polarisFraction}}\\ - Set the fraction of the muon polarisation. The variable \emph{polarisFraction} - has to be set in the range of -1 to 1. \\ - If \emph{polarisFraction} is set to 1, all muons are polarised in the direction - of polarisation vector defined by ``/gun/muonPolarizVector''.\\ - If \emph{polarisFraction} is set to 0, half of the muons are polarised in the direction - of polarisation vector, the second half is polarised in the opposite direction, so - in the end the muon beam should act as unpolarised.\\ - If \emph{polarisFraction} is set to -1, all muons are polarised in the direction - opposite to the polarisation vector.\\ - {\bf If \emph{polarisFraction} is set to 0.9, then 95\% of the muons is polarised - in in the direction of polarisation vector, and 5\% of them is polarised in the - opposite direction!}.\\ - {\bf This command is ignored if magnitude of polarisation vector defined by - ``/gun/muonPolarizVector'' is smaller than 1e-8!} \\ - (Applicable also to TURTLE input). - -\item{\bf /gun/decaytimelimits \emph{muDecayTimeMin} \emph{muDecayTimeMax} \emph{muMeanLife} \emph{unit}}\\ - (default: /gun/decaytimelimits $-1$ $-1$ 2197.03\,ns ) \\ - If {\it muDecayTimeMax} is less or equal to zero, this command is ignored, - and the muon decay time is set internally by {\sc Geant4}. - Otherwise the muon will be forced to decay within a time interval given by - {\it muDecayTimeMin} and {\it muDecayTimeMax}, and the mean muon lifetime will - be set to {\it muMeanLife}. In such case {\it muDecayTimeMin} - has to be equal or larger than 0 and {\it muDecayTimeMax} has to be - larger {\bf or equal} to {\it muDecayTimeMin}.\\ - (Applicable also to TURTLE input). - -\item{\bf /gun/turtlefilename \emph{turtleFileName}}\\ - Set the filename of the TURTLE input file. If this variable is set, TURTLE file - will be used to initiate muons. Otherwise the muons would be generated randomly. - If the end of the TURTLE file is reached (because the user requested to simulate - more events than saved in the TURTLE file), the TURTLE file be be rewind to its - beginning. Note that this does not mean that the same events will be simulated - after the rewind, because the random seed will be set differently than at the - beginning of the simulation. Note that the muons initialised - at the same position and with the same momentum will have completely different - (random) multiple scattering, penetration depths, decay times, - decay positron energies and angles, ..., and therefore will be (almost completely) - different events not affecting the statistical quality of the sample. - -\item{\bf /gun/turtleZ0position \emph{z0\_InitialTurtle} \emph{unit}}\\ - Set the z-position which has been used to generate the TURTLE file.\\ - If this value differs from the $z0$ value of the ``/gun/vertex'' command, - than the particle initial position is extrapolated from $z0\_InitialTurtle$ - to the point corresponding to $z0$, using the direction of its momenta.\\ - MORE DETAILS:\\ - When running TURTLE (e.g. when generating the TURTLE file using the TURTLE program), - the user has to specify the $z$ position, at which the TURTLE particles (muons) would be exported. - Sometimes this $z$ position does not correspond to the point of origin of the musrSim - geometry. In such case, the variable \emph{z0\_InitialTurtle} should be set to the - value, that in musrSim coordinate system corresponds to the point, at which the TURTLE - file was exported. For example -- if the TURTLE file was exported just after the last - quadrupole of a beam-pipe, and in the simulation the edge of the last quadrupole corresponds - to 100\,cm, than the \emph{z0\_InitialTurtle} should be also set to 100\,cm.\\ - -\item{\bf /gun/turtleMomentumBite \emph{turtleMomentumP0} \emph{turtleSmearingFactor} \emph{dummy} }\\ - Modify the smearing of the momentum bite specified in the TURTLE input file. - Normally the muon momentum is defined already in the TURTLE input file. This command allows the user - to modify the momentum smearing (momentum bite) of the muon beam. - The variable \emph{turtleMomentumP0} will be taken as the mean momentum (in MeV/c), around which - the momentum will be increased/decreased. It does not have to be the real mean value of the initial muon momentum distribution. - The variable \emph{turtleSmearingFactor} is the smearing factor in per cent, by which the momentum bite - will be increased/decreased around the \emph{turtleMomentumP0}. The following equation is used to change the - muon momentum: $p_{new}$ = {\it turtleMomentumP0} - ({\it turtleMomentumP0}-$p_{TURTLE}$)$\cdot$0.01$\cdot${\it turtleSmearingFactor}.\\ - This means that:\\ - {\it turtleSmearingFactor} = 100 ... the muon beam momentum will not be modified.\\ - {\it turtleSmearingFactor} = 0 ~~... the muon beam momentum will be set to the constant value of {\it turtleMomentumP0}.\\ - {\it turtleSmearingFactor} = 200 ... the muon beam will have two times broader distribution compared to the original TURTLE file. - -\item{\bf /gun/turtleFirstEventNr \emph{lineNumberOfTurtleFile} }\\ - Set the line number that should be taken as the first event from the TURTLE input file. - This option is needed when the user wants to reproduce the simulation of an event - using the same random number generator and TURTLE initial particle as in some previous - run, however he wants to skip some (uninteresting) events at the beginning of the simulation. - -\item{\bf /gps/*} \\ - In most cases, musrSim uses the so called ``G4ParticleGun'' to generate the primary - particles (muons). The commands for G4ParticleGun were summarised previously, - they start with /gun/ keyword.\\ - However, there is an alternative particle generator - called ``GPS (General Particle Source)'', which is useful when simulating - the decays of radioactive atoms and for other purposes. - Whenever the /gps/ keyword is used, the ``G4ParticleGun'' is not initiated - (and all /gun/* commands are ignored). - The description of GPS can be found on the web, some of the useful commands are:\\ - /gps/particle ion\\ - /gps/ion 38 90 0 0\\ - /gps/position 0 0 0\\ - /gps/energy 0 keV\\ - /gps/ang/maxtheta 2 deg\\ - /gps/ang/maxphi 2 deg\\ - -\end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Detector construction} @@ -446,30 +350,7 @@ Three special volumes ``Target, M0, M1 and M2''. Print out the field value at the point $(x, y, z)$ (given in the global coordinate system. \end{description} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{Visualisation} -\begin{description} -\item{\bf /musr/command visattributes \emph{volumeName} \emph{colour}}\\ - {\bf /musr/command visattributes \emph{materialName} \emph{colour}}\\ - In case of visualisation, - one can set the colour of a logical volume \emph{volumeName} or of all volumes made - of the material with the name \emph{materialName}. The distinction between the - two options is by the first four letters of the \emph{volumeName} -- if it contains - the string ``log\_'', it is considered as \emph{volumeName}, otherwise it is - considered to be a material with \emph{materialName}. - - Presently the following colours are predefined: ``invisible'', ``white'', ``black'', - ``red'', ``darkred'', ``green'', - ``blue'', ``lightblue'', ``darkblue'', ``blue\_style'', ``fblue\_style'', - ``yellow'', ``gray'', ``cyan'', ``magenta'', - ``oxsteel'', ``MCP\_style'', ``MACOR\_style'', ``SCINT\_style'', - ``dSCINT\_style'', ``VTBB\_style'', ``Grid\_style'' and ``RA\_style''. - - New colours can be easily added, if needed, in the member function - ``musrDetectorConstruction::SetColourOfLogicalVolume''. - -\end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Physics processes} @@ -495,6 +376,186 @@ Three special volumes ``Target, M0, M1 and M2''. be defined in the detector construction phase by the command ``/musr/command region define ...''. \end{description} + +%============================================================================================= +\section{Initial (muon) beam parameters} + +\begin{description} +\item{\bf /gun/vertex \emph{x0} \emph{y0} \emph{z0} \emph{unit}}\\ + (default: /gun/vertex 0 0 -100 mm) \\ + Set mean values of the $x$, $y$ and $z$ coordinates of the generated particles (muons). + The smearing around these mean values instead is set by /gun/vertexsigma and + restricted by /gun/vertexboundary (see below).\\ + (Applicable also to TURTLE input). + +\item{\bf /gun/vertexsigma \emph{xSigma} \emph{ySigma} \emph{zSigma} \emph{unit}}\\ + (default: /gun/vertexsigma 0 0 0 mm) \\ + If {\it xSigma} $>0$ ... set $\sigma$, i.e. the standard deviation (RMS), of the $x$ coordinate + of the generated particles (muons) to $\sigma=xSigma$. The $x$ coordinate of the initial + muon is then generated according to the Gaussian distribution with the mean value of $x0$ + and the standard deviation of {\it xSigma}. \\ + If {\it xSigma} $<0$ ... the $x$ coordinate of the initial + muon is generated {\bf uniformly} in the interval of ($x0-$ {\it xSigma}, $x0+$ {\it xSigma}).\\ + If {\it xSigma} $= 0$ ... no smearing on the $x$ coordinate is applied.\\ + Similar is true for {\it ySigma} and {\it zSigma}. \\ + (Ignored by the TURTLE input). + +\item{\bf /gun/vertexboundary \emph{R\_max} \emph{z\_min} \emph{z\_max} \emph{unit}}\\ + Set maximum allowed radius, and minimum and maximum z coordinate of the generated particles (muons). + This command might be useful especially if the user wants to restrict the + area, in which initial particles are created, e.g.\ to force the initial muons + to be created inside the beam pipe. + + If the particles (muons) are read in from an external TURTLE file, + only the restriction on the maximum radius \emph{R\_max} + is applied on the initial particles, while \emph{z\_min} and \emph{z\_max} are ignored. + +\item{\bf /gun/kenergy \emph{kineticEnergy} \emph{unit}}\\ + Set the mean kinetic energy of the initial particles (muons).\\ + (Ignored by the TURTLE input). + +\item{\bf /gun/momentum \emph{momentum} \emph{unit}}\\ + Set the mean momentum of the initial particles (muons).\\ + (Ignored by the TURTLE input). + +\item{\bf /gun/momentumsmearing \emph{momentumSigma} \emph{unit}}\\ + Set $\sigma$, i.e. the standard deviation (RMS), of the momentum spread, which + is applied randomly to each generated initial particle (muon). It is the magnitude + of the momentum, which is smeared. \\ + (Ignored by the TURTLE input. However, + a similar command ``/gun/turtleMomentumBite'' can be used for the TURTLE input file.) + +\item{\bf /gun/momentumboundary \emph{p\_min} \emph{p\_max} \emph{dummy} \emph{unit}}\\ + Set a boundary for the minimum and maximum momentum of the initial particles (muons). + The third argument \emph{dummy} is ignored.\\ + (Presently ignored by the TURTLE input). + +\item{\bf /gun/tilt \emph{xangle0} \emph{yangle0} \emph{dummy} \emph{unit}}\\ + The ``beam tilt'' is understood as a constant angle tilt that is applied to + all initial particles (muons) regardless on their distance from the centre of the beam.\\ + (Applicable also to TURTLE input). + +\item{\bf /gun/tiltsigma \emph{xangleSigma} \emph{yangleSigma} \emph{dummy} \emph{unit}}\\ + Gaussian smearing of the tilt angle.\\ + (Presently ignored by the TURTLE input). + +\item{\bf /gun/pitch \emph{pitch} \emph{unit}}\\ + The ``beam pitch'' is understood as a variable angle applied to the initial particles + (muons), which is directly proportional to the distance from the beam axis. + The particles closer to the beam axis become smaller pitch than particles further away + from the beam axis. + The angle given as \emph{pitch} will be applied to a particle generated 1\,mm away from the + beam centre, i.e. the particle generated 7\,mm away from the beam axis will be assigned + the angle of $7\cdot pitch$. + The pitch allows the user to focus or defocus the initial particle + beam. Particles will be focused for positive pitch and defocused for the negative pitch.\\ + (Applicable also to TURTLE input). + +\item{\bf /gun/muonPolarizVector \emph{xpolaris} \emph{ypolaris} \emph{zpolaris}}\\ + Set polarisation of the initial particle (muon) in a form of a vector + $P=(xpolaris,ypolaris,zpolaris)$. The polarisation vector does not have to be normalised, + the normalisation will be done internally by the program. + However note that if the magnitude of P is set to less than 1e-8, the user can + achieve an unpolarised muon beam. See the source code of musrPrimaryGeneratorAction.cc + if you need to use unpolarised beam by this parameter, because there is some trick + based on the magnitude of P.\\ + (Applicable also to TURTLE input). + +\item{\bf /gun/muonPolarizFraction \emph{polarisFraction}}\\ + Set the fraction of the muon polarisation. The variable \emph{polarisFraction} + has to be set in the range of -1 to 1. \\ + If \emph{polarisFraction} is set to 1, all muons are polarised in the direction + of polarisation vector defined by ``/gun/muonPolarizVector''.\\ + If \emph{polarisFraction} is set to 0, half of the muons are polarised in the direction + of polarisation vector, the second half is polarised in the opposite direction, so + in the end the muon beam should act as unpolarised.\\ + If \emph{polarisFraction} is set to -1, all muons are polarised in the direction + opposite to the polarisation vector.\\ + {\bf If \emph{polarisFraction} is set to 0.9, then 95\% of the muons is polarised + in in the direction of polarisation vector, and 5\% of them is polarised in the + opposite direction!}.\\ + {\bf This command is ignored if magnitude of polarisation vector defined by + ``/gun/muonPolarizVector'' is smaller than 1e-8!} \\ + (Applicable also to TURTLE input). + +\item{\bf /gun/decaytimelimits \emph{muDecayTimeMin} \emph{muDecayTimeMax} \emph{muMeanLife} \emph{unit}}\\ + (default: /gun/decaytimelimits $-1$ $-1$ 2197.03\,ns ) \\ + If {\it muDecayTimeMax} is less or equal to zero, this command is ignored, + and the muon decay time is set internally by {\sc Geant4}. + Otherwise the muon will be forced to decay within a time interval given by + {\it muDecayTimeMin} and {\it muDecayTimeMax}, and the mean muon lifetime will + be set to {\it muMeanLife}. In such case {\it muDecayTimeMin} + has to be equal or larger than 0 and {\it muDecayTimeMax} has to be + larger {\bf or equal} to {\it muDecayTimeMin}.\\ + (Applicable also to TURTLE input). + +\item{\bf /gun/turtlefilename \emph{turtleFileName}}\\ + Set the filename of the TURTLE input file. If this variable is set, TURTLE file + will be used to initiate muons. Otherwise the muons would be generated randomly. + If the end of the TURTLE file is reached (because the user requested to simulate + more events than saved in the TURTLE file), the TURTLE file be be rewind to its + beginning. Note that this does not mean that the same events will be simulated + after the rewind, because the random seed will be set differently than at the + beginning of the simulation. Note that the muons initialised + at the same position and with the same momentum will have completely different + (random) multiple scattering, penetration depths, decay times, + decay positron energies and angles, ..., and therefore will be (almost completely) + different events not affecting the statistical quality of the sample. + +\item{\bf /gun/turtleZ0position \emph{z0\_InitialTurtle} \emph{unit}}\\ + Set the z-position which has been used to generate the TURTLE file.\\ + If this value differs from the $z0$ value of the ``/gun/vertex'' command, + than the particle initial position is extrapolated from $z0\_InitialTurtle$ + to the point corresponding to $z0$, using the direction of its momenta.\\ + MORE DETAILS:\\ + When running TURTLE (e.g. when generating the TURTLE file using the TURTLE program), + the user has to specify the $z$ position, at which the TURTLE particles (muons) would be exported. + Sometimes this $z$ position does not correspond to the point of origin of the musrSim + geometry. In such case, the variable \emph{z0\_InitialTurtle} should be set to the + value, that in musrSim coordinate system corresponds to the point, at which the TURTLE + file was exported. For example -- if the TURTLE file was exported just after the last + quadrupole of a beam-pipe, and in the simulation the edge of the last quadrupole corresponds + to 100\,cm, than the \emph{z0\_InitialTurtle} should be also set to 100\,cm.\\ + +\item{\bf /gun/turtleMomentumBite \emph{turtleMomentumP0} \emph{turtleSmearingFactor} \emph{dummy} }\\ + Modify the smearing of the momentum bite specified in the TURTLE input file. + Normally the muon momentum is defined already in the TURTLE input file. This command allows the user + to modify the momentum smearing (momentum bite) of the muon beam. + The variable \emph{turtleMomentumP0} will be taken as the mean momentum (in MeV/c), around which + the momentum will be increased/decreased. It does not have to be the real mean value of the initial muon momentum distribution. + The variable \emph{turtleSmearingFactor} is the smearing factor in per cent, by which the momentum bite + will be increased/decreased around the \emph{turtleMomentumP0}. The following equation is used to change the + muon momentum: $p_{new}$ = {\it turtleMomentumP0} - ({\it turtleMomentumP0}-$p_{TURTLE}$)$\cdot$0.01$\cdot${\it turtleSmearingFactor}.\\ + This means that:\\ + {\it turtleSmearingFactor} = 100 ... the muon beam momentum will not be modified.\\ + {\it turtleSmearingFactor} = 0 ~~... the muon beam momentum will be set to the constant value of {\it turtleMomentumP0}.\\ + {\it turtleSmearingFactor} = 200 ... the muon beam will have two times broader distribution compared to the original TURTLE file. + +\item{\bf /gun/turtleFirstEventNr \emph{lineNumberOfTurtleFile} }\\ + Set the line number that should be taken as the first event from the TURTLE input file. + This option is needed when the user wants to reproduce the simulation of an event + using the same random number generator and TURTLE initial particle as in some previous + run, however he wants to skip some (uninteresting) events at the beginning of the simulation. + +\item{\bf /gps/*} \\ + In most cases, musrSim uses the so called ``G4ParticleGun'' to generate the primary + particles (muons). The commands for G4ParticleGun were summarised previously, + they start with /gun/ keyword.\\ + However, there is an alternative particle generator + called ``GPS (General Particle Source)'', which is useful when simulating + the decays of radioactive atoms and for other purposes. + Whenever the /gps/ keyword is used, the ``G4ParticleGun'' is not initiated + (and all /gun/* commands are ignored). + The description of GPS can be found on the web, some of the useful commands are:\\ + /gps/particle ion\\ + /gps/ion 38 90 0 0\\ + /gps/position 0 0 0\\ + /gps/energy 0 keV\\ + /gps/ang/maxtheta 2 deg\\ + /gps/ang/maxphi 2 deg\\ + +\end{description} + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Some other parameters} % @@ -724,6 +785,33 @@ The list of variables that can be stored in the Root tree: \item{\bf save\_ke[save\_n]} (array of Double\_t) -- kinetic energy of the particle when it entered the save volume (in MeV). \end{description} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Visualisation} + +\begin{description} +\item{\bf /musr/command visattributes \emph{volumeName} \emph{colour}}\\ + {\bf /musr/command visattributes \emph{materialName} \emph{colour}}\\ + In case of visualisation, + one can set the colour of a logical volume \emph{volumeName} or of all volumes made + of the material with the name \emph{materialName}. The distinction between the + two options is by the first four letters of the \emph{volumeName} -- if it contains + the string ``log\_'', it is considered as \emph{volumeName}, otherwise it is + considered to be a material with \emph{materialName}. + + Presently the following colours are predefined: ``invisible'', ``white'', ``black'', + ``red'', ``darkred'', ``green'', + ``blue'', ``lightblue'', ``darkblue'', ``blue\_style'', ``fblue\_style'', + ``yellow'', ``gray'', ``cyan'', ``magenta'', + ``oxsteel'', ``MCP\_style'', ``MACOR\_style'', ``SCINT\_style'', + ``dSCINT\_style'', ``VTBB\_style'', ``Grid\_style'' and ``RA\_style''. + + New colours can be easily added, if needed, in the member function + ``musrDetectorConstruction::SetColourOfLogicalVolume''. + +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \clearpage %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -756,6 +844,10 @@ in~\cite{Aktas:2004px}. \begin{thebibliography}{0} +\bibitem{shirokaGeant} +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],