Datacard Documentation

Datacard Documentation

G4MICE applications are controlled by a datacard file invoked on the command line when an application is run, for example by typing ApplicationName CardFileName. Datacards can contain many control variables all of which listed below. Datacards are specified by a name, followed by its value, followed by a unit if appropriate. If a datacard is not listed, the default will be used instead, as specified below. Use an exclamation mark to comment out a line in the datacard file. Example datacard files can be found in several application areas. A few datacards require vector entries. Here, the entry should be specified by an integer for the number of entries, followed by space separated values, followed by units.

Global run control
CardTypeDefault ValueDescription
numEvts integer 100  Number of events in the run
runNumber integer 1  Run number listed in header of some output files
Description string G4MICE events   Description of the run listed in the header of some output files
VerboseLevel integer 1  Set to minimum level of error that will be output by G4MICE. 0=debug 1=info 2=warning 3=error 4=fatal >4=silent
DataType string TextFile   The data type of the dataCards file, set by user and used in global reader, TextFileReader etc
Modelling and Configuration
CardTypeDefault ValueDescription
MiceModel string MICEStage6/Stage6.dat   The MiceModel, as defined in $MICEFILES/Models/Configurations/
SciFiCalib string   SciFi detector calibration file, found in ${MICEFILES}/Calibration/
TofCalib string tofcalib   TOF detector calibration file, found in ${MICEFILES}/Calibration/
SciFiCable string   SciFi detector cabling file, found in ${MICEFILES}/Cabling/SciFi/
SciFiCableType string   Set to "Imperial" or "Osaka" for different cabling types
TofCable string tofcabling.txt   Tof detector cabling file, found in ${MICEFILES}/Cabling/
FieldGridX integer 2  Number of points in the field grid in x. As an optimisation, G4MICE divides the world into a grid. At each step, G4MICE only looks at fields in the local grid. The number of points in each dimension should roughly match the size of the problem in each dimension for a reasonable option, and FieldGridX*FieldGridY*FieldGridZ should be small, say<1e6.
FieldGridY integer 2  Number of points in the field grid in y
FieldGridZ integer 100  Number of points in the field grid in z
Simulation Application run control
CardTypeDefault ValueDescription
MaxRadiusInChannel float 1.e9 * mm  Events with r = sqrt(x^2 + y^2) > MaxRadius in global coordinates are killed
MaxZInChannel float 1.e9 * mm  Events with z > MaxZ are killed in Simulation
MaxTimeAllowed float 1. * ms  Events with t > MaxT are killed in Simulation
RandomSeed integer 0  Random seed for stochastic algorithms
PhysicsModel string QGSP_BERT   Physics package loaded by G4MICE to set default values; modifications can be made as per following
MultipleScatteringModel string mcs   "mcs" (multiple coulomb scattering) or "none"
EnergyLossModel string estrag   "estrag" (full energy loss), "ionisation" (mean energy loss only) or "none"
HadronicModel string All   "All" (All hadronic interactions) or "None" (no hadronic interactions)
MuonDecay string   Deprecated; please use ParticleDecay datacard
ParticleDecay string True   Set to "True" or "False" to determine whether muons decay
ReferenceEnergyLossModel string ionisation   Energy loss model of reference particle; set to "none" or "ionisation". Reference particle can never have stochastic processes (e.g. estrag, mcs) enabled.
ReferenceG4UIScript string   If a filename is given, G4MICE will run this as a macro to G4UI after setting up ReferenceEnergyLossModel but before firing the reference particle. Enables any extra set-up that may be required.
BeginOfRunG4UIScript string   If a filename is given, G4MICE will run this as a macro to G4UI after firing the reference particle but before firing the beam. Enables any extra set-up that may be required.
EverythingSpecialVirtual string   Set to "true" to make every physical volume a special virtual detector
WriteReferenceParticle integer 0  Set to 1 to write reference particle hits during simulation; or 0 to ignore them
ProductionThreshold float 0.5 * mm  I *think* threshold for delta ray production
MuonHalfTime float -1 * ns  Set the muon half life; use g4 default if negative.
ChargedPionHalfTime float -1 * ns  Set the pi+ and pi- half life; use g4 default if negative.
TrackOnlyMuons string False   Set to true to kill non-muons on production
MaxStepsWOELoss integer 2000  Maximum number of steps GEANT4 will take without energy loss. Subsequently, assumes particle is stuck and kills it
StepStatisticsOutput integer 0  I *think* set to 1 to see physics processes output
StepStatisticsVolume string All   I *think* selects which volumes to write physics processes output from
CheckVolumeOverlaps integer 0  Set to 1 to check for volume overlaps in GEANT4 physical volumes
Simulation Application beam control
CardTypeDefault ValueDescription
BeamType string Pencil   Type of beam; "Pencil" generates a pencil beam using parameters below, "Gaussian" generates a beam with gaussian distribution using parameters below, "ICOOL", "G4BeamLine", "TURTLE", "G4MICE_PrimaryGenHit" set G4MICE to read from a beam file with the appropriate format and file name defined in datacard "InputBeamFileName"; "MiceModule" uses the beam definition taken from MiceModules (see mice module docs), and allows arbitrary placement of beams with arbitrary multivariate gaussian distributions; in general, MiceModules are the preferred method for setting up beams. The reference particle is the first particle created. If BeamType is Random, the first particle will have no random distribution.
BeamMomentum float 200.0 * MeV  When BeamType is Pencil or Random, controls momentum of the beam
ZOffsetStart float -6011. * mm  Z-position of input beam when not in MiceModule mode. x and y are 0. Added to any z-position in beam file.
BeamPid integer -13  Particle ID of pencil beam and TURTLE beam (11 is e-, -13 is mu+, 211 is pi+, 2212 is proton)
InputBeamFileName string none   Name of beam file for BeamTypes that use files, as specified in BeamType above
SigmaX float 0.*mm  If beam type is "Gaussian", set RMS of x
SigmaXPrime float 0.  If beam type is "Gaussian", set RMS of x' (px/p)
SigmaY float 0.*mm  If beam type is "Gaussian", set RMS of y
SigmaYPrime float 0.  If beam type is "Gaussian", set RMS of y' (py/p)
SigmaT float 0.*ns  If beam type is "Gaussian", set RMS of time distribution
SigmaEOverE float 0.  If beam type is "Gaussian", set RMS of (E-E_ref)/E_ref where E is total energy and E_ref is total energy corresponding to BeamMomentum
Beam Matcher Application Control
CardTypeDefault ValueDescription
MatchAlgorithm string EigenvalueSeed   The algorithm used for matching; "Eigenvalue" calculates the transfer map and then attempts to automatically derive the matched covariance matrix; "EigenvalueSeed" uses this automatic calculation as the seed for a numerical for a periodic solution, including e.g. some effects of material; "UserDefined" uses user input for the Twiss parameters at the LatticeStart; "UserDefinedSeed" uses user input for the seed Twiss parameters, and then iterates through an optimisation algorithm to find a periodic solution.
NormalisedCanonicalAngularMomentum float 0  Normalised canonical angular momentum of beam at lattice start
LatticeStart float -2750 * mm  Start of lattice over which beta is periodic
LatticeEnd float 2750 * mm  End of lattice over which beta is periodic
EnergyAtLatticeStart float 226 * MeV  Desired energy at start of the lattice
AlphaBetaScaleFactor float 11/0.05  Weighting factor between alpha and beta for "Seed" algorithms
TransverseEmittance float 6 * mm  Transverse emittance of generated beam
LongitudinalEmittance float 0.1 * ns  Longitudinal emittance of generated beam
AmplitudeMomentumCorrelation float 0.  amplitude momentum correlation introduces factor like p *= (1+(A-)*corr) to matched beam
NumberOfEnergyCoordinates integer 1  Calculate matched beta function for various energies
EnergyRange float 0. * MeV  full energy range over which the multiple beta functions will be calculated
LongitudinalBeta float 10.  longitudinal beta at z = LatticeStart; set to < 0. to auto-detect
LongitudinalAlpha float 0.  longitudinal alpha at z = LatticeStart; only used if auto-detect is off
TransverseBeta float 420. * mm  transverse beta at z = LatticeStart; set to < 0. to auto-detect
TransverseAlpha float 0.  transverse alpha at z = LatticeStart; only used if auto-detect is off
DispersionX float 0. * mm  Future development: x dispersion at z = LatticeStart for matcher
DispersionY float 0. * mm  Future development: y dispersion at z = LatticeStart for matcher
Solenoids Field Controls
CardTypeDefault ValueDescription
FieldMode string Full   "Full" = use G4MICE field definitions; "Constant" = use G4 constant fields
SolDataFiles string Write   "Write" = write solenoid field maps; "Read" = read solenoid field maps
NumberNodesZGrid integer 100  Default number of nodes in Z in the solenoid field map grid
NumberNodesRGrid integer 150  Default number of nodes in R in the solenoid field map grid
SolzMapExtendFactor float 10.0  Set the Z extent of the solenoid field maps; z_extent of the field map = coil_length + z_factor*coil_inner_radius
SolrMapExtendFactor float 2.01828182845905  Set the radial extent of solenoid field maps; r_extent of the field map = r_factor * coil_inner_radius
DefaultNumberOfSheets integer 10  number of sheets for solenoids.
Quadrupole Field Controls
CardTypeDefault ValueDescription
QuadrupoleFringeMaxZFactor float 5.  Maximum z extent of quadrupole fringe fields (as a fraction of quad length)
QuadrupoleUseFringeFields integer 1  Set to 1 to use fringe fields in quadrupoles
QuadrupoleFringeParameters vector {0.296471, 4.533219, -2.270982, 1.068627, -0.036391, 0.022261}  Default parameters for Enge function, that controls multipole fringe fields
RF Cavity Field Controls
CardTypeDefault ValueDescription
rfAccelerationPhase float 1.57 * rad  Default RF phase of all cavities. May go buggy if this is > pi/2 so be careful
OpticsRfFrequency float 201.25 * megahertz  Global RF frequency assumed by optics module.
PhaseTolerance float 1e-5 * ns  Tolerance on RF phase
RFDeltaEnergyTolerance float 1e-5 * MeV  Tolerance on RF energy gain (peak field)
Simulation Application stepping parameters
CardTypeDefault ValueDescription
DeltaOneStep float 1. * mm  Estimate of error in end point in free space
DeltaIntersection float 1.e-3 * mm  Estimate of error in step end point when a track intersects a new physical volume
EpsilonMin float 1.e-10 * mm  Minimum on DeltaOneStep? (unclear in G4 docs)
EpsilonMax float 1.e+10 * mm  Maximum on DeltaOneStep? (unclear in G4 docs)
MissDistance float 1.e-2 * mm  Maximum miss distance when a track passes near a physical volume
FieldTrackStepper string Classic   Set the integration algorithm for tracking. Options are for electromagnetic: "Classic" (= "ClassicalRK4"); "SimpleHeum"; "ImplicitEuler"; "SimpleRunge"; "ExplicitEuler"; and for magnetic only: "CashKarpRKF45"; "HelixImplicitEuler"; "HelixHeum"; "HelixSimpleRunge"; "HelixExplicitEuler". see G4 documentation for further details.
VirtualRelativeError float 1.e-4  Relative error for virtual detector stepping
VirtualAbsoluteError float 1.e-4  Absolute error for virtual detector stepping
MaxStepSizeInChannel float 10000.0 * mm  Deprecated - does nothing
Simulation Application RF induced background controls - Deprecated do not use
CardTypeDefault ValueDescription
rfBGMode string none   Deprecated - does nothing
rfBGSource string none   Deprecated - does nothing
rfBGElectronModel string Simple   Deprecated - does nothing
rfBGPhotonModel string Uniform   Deprecated - does nothing
rfBGEmitterMode string Random   Deprecated - does nothing
rfBGNumberOfEmitters integer 10  Deprecated - does nothing
rfBGNumberOfElectrons integer 1  Deprecated - does nothing
rfBGNumberOfPhotons integer 1  Deprecated - does nothing
rfBGDirection integer 0  Deprecated - does nothing
rfBGElectronEnergy float .01 * MeV  Deprecated - does nothing
rfBGPhotonEnergy float .1 * MeV  Deprecated - does nothing
rfBGElectronEnergyWidth float .001 * MeV  Deprecated - does nothing
rfBGPhotonEnergyWidth float .01 * MeV  Deprecated - does nothing
rfBGElectronSpectrum string Fixed   Deprecated - does nothing
rfBGPhotonSpectrum string Fixed   Deprecated - does nothing
rfBGElectronSpectrumFile string   Deprecated - does nothing
rfBGPhotonSpectrumFile string   Deprecated - does nothing
rfBGMultipleSpectraFile string None   Deprecated - does nothing
rfBGBankFile string None   Deprecated - does nothing
rfBGSamplingMode string Loop   Deprecated - does nothing
rfBGTimeWindow float 0.2 * ns  Deprecated - does nothing
rfBGTimeDelay float 0.0 * ns  Deprecated - does nothing
rfBGZstart float 0.0 * ns  Deprecated - does nothing
rfBGRadius float 150.0 * mm  Deprecated - does nothing
rfBGScaleFactor float 1.0  Deprecated - does nothing
Digitization Application Calorimeter Controls
CardTypeDefault ValueDescription
EMCalAttLengthLong float 2400.0 * mm  The EM Calorimeter models the number of photoelectrons entering the PMT using Interface/src/EMCalDigit.cc
EMCalAttLengthShort float 200.0 * mm 
EMCalAttLengthLongNorm float 0.655 * mm 
EMCalAttLengthShortNorm float 0.345 * mm 
EMCalLightCollectionEff float 0.031 
EMCalEnergyPerPhoton float 0.125 * keV 
EMCalLightSpeed float 170.0 * mm / ns 
EMCalLightGuideEff float 0.85 
EMCalQuantumEff float 0.18 
EMCalAmplificationCof float 1000000. 
EMCalAmplificationFluct float 1000. 
EMCalAdcConversionFactor float 0.25*1e-12*coulomb  pC per count
EMCalTdcConversionFactor float 0.025 * ns 
EMCalAdcThreshold integer 2  adc counts
EMCalTdcThreshold float 1.84*1e-12*coulomb  pC
EMCalTdcResolution float 0.05 * ns 
EMCalTdcBits integer 12 
EMCalHardCodedTrigger string False  
EMCalSamplingTimeStart float 100.0 * ns 
EMCalSamplingTimeWindow float 100.0 * ns 
EMCalElectronicsDecayTime float 8.0 * ns 
Digitization Application SciFi controls
CardTypeDefault ValueDescription
SciFiDeadChanFName string  
SciFiMUXNum integer 7 
SciFiFiberDecayConst float 2.7 
SciFiFiberConvFactor float 3047.1 
SciFiFiberRefractiveIndex float 1.6 
SciFiFiberCriticalAngle float 0.4782 * rad 
SciFiFiberTrappingEff float 0.056 
SciFiFiberMirrorEff float 0.6 
SciFiFiberTransmissionEff float 0.8 
SciFiMUXTransmissionEff float 1.0 
SciFiFiberRunLength float 5000.0 * mm  ME this number is wrong
SciFivlpcQE float 0.8 
SciFivlpcEnergyRes float 4.0 * MeV 
SciFivlpcTimeRes float 0.2 * ns 
SciFiadcBits integer 8 
SciFiadcFactor float 6.0 
SciFitdcBits integer 16 
SciFitdcFactor float 1.0 
SciFinElecChanPerPlane integer 1429 
SciFinPlanes integer 3 
SciFinStations integer 5 
SciFinTrackers integer 2 
Digitization Application TOF controls
CardTypeDefault ValueDescription
TOFconversionFactor float 10 * keV 
TOFpmtTimeResolution float 100.0 * picosecond 
TOFattenuationLength float 140 * cm 
TOFadcConversionFactor float 0.125 
TOFtdcConversionFactor float 25.0 * picosecond 
TOFpmtQuantumEfficiency float 0.25 
TOFscintLightSpeed float 170.0 * mm / ns 
Digitization Application Ckov controls
CardTypeDefault ValueDescription
CKOVadcConversionFactor float 0.125 
CKOVtdcConversionFactor float 25.0 * picosecond 
CKOVpmtTimeResolution float 100.0 * picosecond 
Reconstruction Application controls
CardTypeDefault ValueDescription
BeamCharge float 1.0 
SciFiTrackRecStatusCut float 2.0 
SciFiTrackRecRCut float 0.0 
SciFiTrackRecNHitCut float 4.0 
SciFiTrackRecNPECut float 2.0 
SciFiTrackRecChi2Cut float 10.0 
SciFiTripletChi2Cut float 10.0 
SciFiadcFactor float 6.0 
SciFitdcFactor float 1.0 
SciFiCombineWidth float 0.0 * mm 
SciFiCombineTime float 2.0 * ns 
SciFiCombineRadius float 1.5 * mm 
RecP float -1 * MeV 
DBServerHostName string micewww.pp.rl.ac.uk   Database server host name
DBServerPort integer 4443  Database server port
TofTriggerStation integer 1  The Station which is giving the trigger
RecLevel integer 5  1 = clusters, 2 = points, 3 = tracks, 4 = matching, 5 = pid
TofRecLevel integer 1  1 = standard track reconstruction
TofCalibrationMode integer 0  0 = reconstruct data, 1 = calculate calibration
BeamMakerMode integer 1  Matched in tracker/trace ellipse of constant amplitude/uniform distribution... see application for details
BeamMakerPID integer +2  1=e, 2=mu, 3=pi, 4=K, 5=p, sign=charge (same as ICOOL for003.dat definition)
ZStart float 0.  Initial z (absolute) for the BeamMaker application
Q7Gradient float 1.  |g0| in T/m for Quadrupole 7 (assumed focussing in x)
Q8Gradient float 1.  |g0| in T/m for Quadrupole 8 (assumed defocussing in x)
Q9Gradient float 1.  |g0| in T/m for Quadrupole 9 (assumed focussing in x)
Q7Current float 174.09  |I| in Amps for Quadrupole 7 (assumed focussing in x, default implies |g0| = 1 T/m)
Q8Current float 174.09  |I| in Amps for Quadrupole 8 (assumed defocussing in x, default implies |g0| = 1 T/m)
Q9Current float 174.09  |I| in Amps for Quadrupole 9 (assumed focussing in x, default implies |g0| = 1 T/m)
Iperg0 float 174.09  The current required to get a central gradient of 1 T/m in Quadrupoles 7, 8, and 9
PlotFrequency integer 100  For applications which plot histograms to the screen: how many events between updating the plots on the screen?
MinimumTOF float 0. * ns  Temporary PID
MaximumTOF float 100. * ns  Temporary PID
UseRecCuts integer 0  If set to 0, do not use the reconstruction cuts defined below. Otherwise assume all events outside cuts are bad.
RecMinPX float -200 * MeV  Cut value for reconstructed x momentum
RecMaxPX float 200 * MeV  Cut value for reconstructed x momentum
RecMinPY float -200 * MeV  Cut value for reconstructed y momentum
RecMaxPY float 200 * MeV  Cut value for reconstructed y momentum
RecMinPT float 0 * MeV  Cut value for reconstructed transverse momentum
RecMaxPT float 200 * MeV  Cut value for reconstructed transverse momentum
RecMinPZ float 50 * MeV  Cut value for reconstructed z momentum
RecMaxPZ float 500 * MeV  Cut value for reconstructed z momentum
WriteDST integer 0  Set to 1 to write only TOF data and Zustand vectors after recontruction. Else write everything.
NavigatorVerbosity integer 0  Set Kalman verbosity level
FitterVerbosity integer 0  Set Kalman verbosity level
SetupVerbosity integer 0  Set Kalman verbosity level
ModelVerbosity integer 0  Set Kalman verbosity level
MatchingVerbosity integer 0  Set Kalman verbosity level
KalmanStepSize float 10. * cm  Step size for Kalman fitter; used if fields are not constant
KalmanUseFieldMap integer 0  Set to 0 to use a constant field for track fits; set to 1 to use BeamTools (real) fields for reconstruction
Analysis Application controls
CardTypeDefault ValueDescription
AnalysisParametersFile string AnaParams.dat   Auxiliary file for analysis; see $MICESRC/Analysis/doc/
ICOOLfor003StyleFile string for003.dat   icool beam input data file
ICOOLfor009StyleFile string for009.dat   icool beam output data file
AnalysisParticlePdgId integer -13  PDG Particle ID; other events will not be used in the analysis
StartEvent integer 0  Start event - ignores events before this
TransferMapAbsoluteError float 1e-5  Absolute error when Optics package calculates transfer maps
TransferMapRelativeError float 1e-5  Relative error when Optics package calculates transfer maps
OpticsStepSize float 100 * mm  Step size for Optics package
OpticsFileName string Optics.out   Output file name for Optics package
OpticsdEdXModel string BetheBloch   dEdx model for optics package; "MinimumIonising" or "BetheBloch"
OpticsCalculationOrder integer 1  Default order for calculation of optics transfer maps (>1 still doesn't work I'm afraid)
PidInputFile string nnReadStage6.root   Input PID data file for PIDAnalysis application
PidTreeName string eventTree  Input Tree name for PIDAnalysis application
PidBGWeight float 1.  Weighting given to background events in PidAnalysis application
PidAnalysisPlanes integer 1  Planes used in PidAnalysis application 1 = tracker ref, 2 = tof ref central, 3 = tof ref outer, negative = same with smearing