LMU/musrsim
LMU/musrsim
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

2009-05-26 Kamil Sedlak

Browse Source 
Added more information to the documentation files ( doc/musrSim.tex ).
This commit is contained in:
sedlak 2009-05-26 15:56:15 +00:00
parent 1e050e6976
commit e6083ec894
3 changed files with 292 additions and 198 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/dis04.cls
View File

@ -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

BIN
doc/musrSim.pdf
View File

Binary file not shown.

484
doc/musrSim.tex
View File

@ -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],