User knobs, buttons and switches (non-geometry)

Note: This is still fairly preliminary. This is documents most of the non-geometry FFREAD cards that were defined as of 7/2/96 (partially updated 2006-03-14). The details are still subject to change. The use of FFREAD as the basic mechanism was chosen simply for convenience (it is a CERN product, it is straightforward, it works straight out of the box, it's already used by GEANT).

FFREAD long writeup @ CERN

Basic GEANT3 cards

RUNG card

Usage: RUNG runnum evtnum
Set the run number and initial event number.

RNDM card

Usage: RNDM seqno 0
Usage: RNDM seed1 seed2
Set the random number sequence. The first sets a general sequence number, the second attempts to set the actual seed values. Do not use the second form! For GMINOS (most) all of the random number generators are funnelled through RANLUX so only the first method works correctly.

TRIG card

Usage: TRIG nevt
Set the number of events to process. This is an upper limit; other conditions might end the run early (e.g. see POTS).

STAT card

Usage: STAT flga
Keep statistics (use 1).

HSTA card

Some basic histograms.

PRIN card

Print GEANT3 info.

SAVE card

Define what should be written to the GAF (ADAMO) file. The NDIG value supresses the writing of digits (and their generation!); the 'NHIT' supresses the writing of hits.


MXST card

Usage: MXST nsteps
The MXST limits the maximum number of steps GEANT will take while tracking a particle. This is useful for killing off straggling muons or other such junk. In our case it can be something of a problem since we have so many planes. The default for /GCTRAK/MAXNST is 10000 which tends to chop muons off at about 2000 cm in length. The introduction of this card pushes that limit up to 5000 and allows the user to adjust it as they feel necessary.

MKIN card

Usage: MKIN method
Choose method for generating (or importing) events. The user can specify the kinematics by using the usr_kine hook; the events can be read from a file; generated with the neugen (Soudan2) package; specified as the kinematics of a single particle. Additional methods can be added by modifying GUKINE.
    0 = call usr_kine
    1 = call hepevt_file_kine (read "hepevt.dat" STDHEP file)
    2 = call neugen_kine NEUGEN2
   -2 = call neugen_kine NEUGEN3 <== this is your best bet
    3 = call single_part_kine (or if /GCKINE/
          Use with KINE card:
          IKINE = geant particle #
          PKINE(1..3) = particle momentum
          PKINE(4..6) = starting position
    4 = up- and down- going muons
For method 3, one can set the basic kinematics using the KINE FFCARD for input. The first value (an integer) is the *geant* particle code; the next three (real don't forget decimal places!) are the components of the momenta. Under gminos_inter one can change change these before each event using the KINE command. A non-zero IKINE value overrides the general MKIN method independent of what mode was requested.


Usage: HEPEVTFN 'hepevt.dat'
Filename to look for when reading binary /HEPEVT/ files (MKIN=1). If not found locally it will try the name with the path $HEPEVTPATH prepended.

FNDE card

Usage: FNDE ievt
When reading event from event file (MKIN=1) this card allows the user to skip past events at the beginning. A value of 0 means start with first event. A positive number looks for a match of ievt with /HEPEVT/NEVHEP. A negative value means to skip iabs(ievt) events from the beginning of the file before processing the first event.

Events in the rock

Usage: ROCK level
Usage: RSAF rock-min
Usage: RFLXEXPAND flux-window-expansion
Usage: RCYLCUTS 0/1
Control whether events are generated in the rock with ROCK:
  0 = only the detector
 -1 = only the rock
 +1 = both rock and detector
This attempts to optimize the rock volume in which events are generated and avoid tracking events that will never leave any energy deposition in the detector. The RSAF allows one to add some safety margin around the detector that is never excluded no matter how low in energy the event might be (200 cm default). The RFLXEXPAND is extra safety added to the neutrino flux window (200 cm default). The RCYLCUTS controls whether cyclindrical cuts are made around the beam and/or z-axis (better to leave this one alone).

MTDK card

Usage: MTDK method
Method for handling tau decays. Note: the default method (0) is effectively what has always been used, and generates no displacement in the vertex since the tau itself is never propagated in geant.
    0 = NEUGEN+tauola, no displaced vertex (default)
    1 = GEANT GDECAY (not recommended)
    2 = LUND performs the decay
        GEANT tracks the event, GUDCAY call GLUDKY_MINOS
    3 = NEUGEN+tauola for kinematics
        GEANT displaces the vertex by tracking the
        re-animated tau, and substitutes tauola's decay
        products (not intially entered) when the tau decays
    4 = tauola directly in GUDCAY
        NEUGEN told not to call tauola (not yet implemented)

VTRK card

Usage: VTRK vetotrak
Method for vetoing tracks: 'NONE' (default), 'ALL ' 'MUON', 'SHW '. Sets class of tracks not to propagate through the geometry (i.e. no hits).


Usage: RKVMINDIST distance Usage: RKVFACTOR fudge-factor
Events with a vertex generated in the rock are subject to have particles killed off by gukine_veto before they are passed to GEANT for propagation. The criteria for killing a particle is that the particle is charged, the particle vertex is at least distance from the hall and the energy is less than dist-to-hall * dedx_min / fudge-factor, where dedx_min is the min dE/dx calculated by GEANT for a muon in the MARS medium. Use the value -1.25 (note negative!) to recreate the cut prior to Daikon_03 (which had hardcoded value for dedx_min).

CCNC card

Usage: CCNC flag
Limit event types generated by NEUGEN (2 & 3).
   -1 = generate either CC or NC event in right proportions (default)
    1 = generate only CC events
    2 = generate only NC events

INTR card

Usage: INTR p1 p1 p2 p3 p4
Limit event processes generated by NEUGEN3 (not 2!); up to 4 (of the 5 possible) processes can be disabled. Leave unused values at default 0.
    1 = (quasi)elastic
    2 = resonant production
    3 = DIS
    4 = coherent
    5 = neutrino-electron scattering (IMD)
Use a one-to-one mapping to specify what to disable; this is not a list of the process numbers to disable but base on placement. That is, to generate only coherent events the card should be:
INTR 1 2 3 0 5
The actual values don't matter, so could as easily be:
INTR 1 1 1 0 1

QELR card

Usage: QELR flag
Limit event types generated by NEUGEN2 (not NEUGEN3).
   -1 = generate either QEL or Inelastic events (default)
    0 = generate only QEL events
    1 = generate only DIS events

RSCT card

Usage: RSCT flag
Control nuclear re-scattering in NEUGEN.
    0 = no rescattering, INTRANUKE not called
    1 = INTRANUKE called (default)
    2 = INTRANUKE ("strong" in NEUGEN3 only)

HQDK card

Usage: HQDK flag
Control who performs decay of heavy quark hadrons. (?? works for both NEUGEN2 and NEUGEN3???). Default 0.
   0 = NEUGEN/PYTHIA promptly decays heavy Q states (i.e. charm hadrons)
   1 = GEANT propagates heavy Q hadrons, LUND handles decay kinematics

PDFG and PDFS cards

Usage: PDFG group
Usage: PDFS set
Force NEUGEN (2 and 3) to use the selected Parton Distribution Functions (PDFLIB's numbering conventions).

TAUB card

Usage: TAUB flag
Limit tau decay modes used by TAUOLA/NEUGEN (NEUGEN2 only????)
    0 = generate with TAUOLA branching ratios (default)
    1 = force  tau -> e
    2 = force  tau -> mu
    3 = force  tau -> pi
    4 = force  tau -> rho
    5 = force  tau -> a1
    6 = force  tau -> K
    7 = force  tau -> K*

DKOF card

Usage: DKOF ipdg1 ipdg2 ...
Turn off NEUGEN's (NEUGEN2 only!) decay of individual particles types. Particle types s hould be identified by PDG numbers; particles unknown to NEUGEN are ignored.

DISG card

Usage: DISG 0
Force NEUGEN2 to use PYTHIA/JETSET for DIS hadronization.

PLNL, FIDB and FIDZ cards

Usage: PLNL first_plane last_plane
Usage: FIDB R_outer R_inner
Usage: FIDZ R_outer R_inner x0 y0
Fiducial cuts on generated event vertices. The PLNL (plane limits) card limits the range of plane numbers, the other two are based on tubes (annulii in cross section); only vertices that lie within the outer and inner radii of both cylinders (and satisfy the PLNL card) will be generated. The FIDB card specifies the outer and inner radii of a tube directed (and centered) along the beam axis. The FIDZ card defines two concentric cylinders parallel to the z axis, centered on the point (x0,y0).

Take care not to specify an impossible condition set. If the intersection of all the selection criteria is a null volume, this condition is not tested for and will result in an infinite loop.


Usage: MFLX method
Usage: FFLX 'auxillary_file_name'
Usage: FLXL emin emax
Choose method for generating neutrino flux with MFLX. Method 0 requires no additional files (all pertinent data is dataified in the routine), but this method is only appropriate for use with a "Far" detector setup. Additional methods can be added by modifying GET_NU and GET_NU_INIT.
    0 = E pulled from histograms (no transverse momentum)
        relative flavors of nu_e,nu_e~,nu_mu,nu_mu~ based on gbeam
        uniformly distributed across flux window
    1 = Miller/Mufson flux files.
    2 = Peter Litchfields flux format for cosmic neutrinos
        (similar to 1, but energy scale is MeV)
    3 = read in R. Hatcher flux format; this format avoids trig overhead
        of method 1 and fixes some coordinate transform errors
        in that code.  Flux is derived from reweighting code of
        J. Hylen (row-wise) ntuples.
    4 = flux of nu_mu's with 1/E spectrum (use FLXL card
        to set reasonable lower limit).
    5 = GNUMI column-wise ntuples
The FFLX allows the user to pass the flux method a file name (which it may or may not use). For MFLX=5 this can be a wildcard list of files.

MFLX=5 specific cards

Usage: POTS pot-limit
Usage: F5OP max_rewind maxuse_hgntf
Usage: LOADALLG 0 or 1
Usage: EXTERNPOTSPERFILE pots-per-file
The POTS card stops event generation when the limit has been reached. The F5OP controls how often gnumi ntuple files/entries are used before moving on to the next. The LOADALLG controls whether all the columns are loaded or only the minimum necessary; EXTERNPOTSPERFILE overrides the POTS count found in the file.

Up- and Down-going muon (MKIN=4) cards

Usage: ATMD mudirection
Usage: ATMF 'upgoing-muon-flux-histfile
Usage: ADMF 'downgoing-muon-flux-histfile
Usage: ADEX downmu-extend-spectra-flag
Usage: ADMUE downmu-uniform-max-energy
If ATMD is 0 then the muons are up-going; non-zero means down. The ADMUE card (by default -1), if set to a postive value, sets downgoing muon energy spectrum to be uniform from 0 to value; if negative the routine uses the orginal histograms. Other details to come ... or just look at the code yourself

BCEN, BSLP and PREL cards

Usage: BCEN beam_x0 beam_y0 beam_z0
Usage: BSLP beam_dxdz beam_dydz
Usage: PREL plane
Position of the beam center and the slopes relative to the detector (MARS) co-ordinate system. If PREL is non-zero this is relative to that plane. This is used in determining the reference plane on which neutrinos are placed.

ZREF and FREF cards

Usage: ZREF z_tgt2ref
Usage: FREF ref_z_nominal
These are relevant to the Miller/Mufson (MFLX=1) and GNUMI (MFLX=5) flux files.
The z_tgt2ref variable is the desired z distance from the beamline z0 (not really the target) to the reference plane of starting events. The ref_z_nominal value should reflect what was used in generating the flux file (only for MFLX=1).

Neutrino flavor changing cards

Usage: MFLV method
Usage: PFLV ipdg1 ipdg2 ipdg3 ipdg4 ipdg5 ipdg6
Usage: OMODE '3WAY'
Usage: ODMSQ dmsq12 dmsq23
Usage: OTHETA theta12 theta13 theta23
Usage: ODCP cp-violating phase radians
Usage: OSCP dms23 dms12 th12 th13 th23 alpha delta
The currently implemented "oscillation" methods (MFLV) are:
    0 = leave neutrino type unchanged
    1 = fixed mapping between flavors (using PFLV)
    2 = David Petyt's oscillation package
    3 = Mark Messier's oscillation package
For method 1, the PFLV array (6 values) hold the integer PDG id for what nu_e, nu_mu, nu_tau, nu_e~, nu_mu~, nu_tau~ will become. Each value must be a legal neutrino code:
neutrino - anti-neutrino
nu_e +12 nu_e~ -12
nu_mu +14 nu_mu~ -14
nu_tau+16 nu_tau~-16
Use OMODE, ODMSQ, OTHETA ODCP for D. Petyt's package; use OSCP for M. Messier's package.

SXYZ card

Usage: SXYZ ilevel
Most useful during interactive sessions, should be set to 0 for batch processing. This flag causes a call to GSXYZ to store the current position during GUSTEP.
C SAVE_XYZ    - controls whether GUSTEP calls GSXYZ
C                 if 0 nothing stored
C                 if - store only charged particles (+ store for all)
C                 if abs=1 store only position in active detector
C                       (2 store all steps)
C   .... restrict it to only entrance point due to possibility
C        of tiny step sizes in the sensitive volumes

GAFF, GAFN and HRFN cards

Usage: GAFF iformat
Usage: GAFN 'file_name.xx_gaf' Usage: HRFN 'gminos.rz'
The first two cards set the name and format of the GAF (Generic Adamo File) output. A format of 0 is an ascii file, 1 is an exchange format FZ file. The gaf file name can be up to 80 characters. They should be enclosed within single quotes. If the file extension is '.xx_gaf' then the 'xx' part will be replaced by "ie" or "fz" for ascii/fz files. The HRFN sets the name of the output hbook file.

WGAF card

Usage: WGAF write_veto
Controls whether to write events:
  0 = write all events to GAF file
  1 = write only those with non-empty hit or digit tables
  2 = write only those with non-empty hit tables


Usage: ALTDEDX use-alt
Use modified dE/dx routines (see Mike Kordosky for details). Default is 1.


Usage: HITTRIM nhits-per-trig nhits-target-max nhits-per-plane-min
Attempt to prevent ZEBRA overflow by throwing away hits to achieve limits.

ACPT card

Usage: ACPT flag
If non-zero and MKIN=±2 (ie. NEUGEN2 or NEUGEN3) then perform addition event acceptance cuts ($GMINOSPATH/kine/accept_neugen_kine.F). The default routine passes only events with charm or bottom hadrons somewhere in the result

C2ND and SAVT cards

Usage: SAVT evtnum1 evtnum2 ...evtnum100
Usage: C2ND threshold-process-1 threshold-process-2 ...
The SAVT is a list of event # (idevt) in which to save intermediate track info. Save to StdHep's /HEPEVT/ (limited to 4000 lines). List can contain 100 events; adjacent pairs of negative values denote a range of events. The C2ND card controls the threshold (GeV) for saving secondary particle to /HEPEVT/; one threshold per GEANT process. If the value is positive then any particle with PTOT greater than threshold saves all the secondaries in that interaction; if negative then only those particles over threshold are recorded. By repeating the card one can overwrite individual values after setting an initial default. ie.
          C2ND 60*0.020
          C2ND 9=0.150 10=0.150 11=0.150
sets a limit of 20MeV for all processes except BREM,DRAY,ANNI which use 150MeV. (default is 0.150). Process are:
           1='NEXT'  2='MULS'  3='LOSS'  4='FIEL'  5='DCAY'
           6='PAIR'  7='COMP'  8='PHOT'  9='BREM' 10='DRAY'
          11='ANNI' 12='HADR' 13='ECOH' 14='EVAP' 15='FISS'
          16='ABSO' 17='ANNH' 18='CAPT' 19='EINC' 20='INHE'
          21='MUNU' 22='TOFM' 23='PFIS' 24='SCUT' 25='RAYL'
          26='PARA' 27='PRED' 28='LOOP' 29='NULL' 30='STOP'
          31='LABS' 32='LREF' 33='SMAX' 34='SCOR' 35='CKOV'
          36='REFL' 37='REFR' 38='SYNC' 39='STRA'

Active detector switches

FATL and FATN cards

Usage: FATL attn_len_short attn_len_long
Usage: FATN attn_norm_short attn_norm_long
Set the FLS fiber attenuation lengths. Provisions are made for a two component system. The defaults are (350cm,1100cm) and (1.0,0.66).

STUB card

Usage: STUB fiber_tail
The additional length of fiber beyond the detector edge (currently default of 100cm).

PEMU and ELMU cards

Usage: PEMU pe_per_muon
Usage: ELMU energy_loss_per_muon
This set is not yet fully implemented. PEMU, ELMU are used to set the overall normalization. PEMU *should* the number of experimentally observed photo-electrons seen for a muon; ELMU should be the true energy loss by the muon. There should also be cards for the photodetector efficiency, the fiber waveshift time constant (add to FATL,FATN above), and the mirror end reflectivity.

QEPD card

Usage: QEPD photodetector_eff
This is the photo-detector quantum efficiency in the range from 0 to 1 (default 0.10). This is not multiplied against the PEMU value, but rather affects only the Poisson statistics.

WTAU card

Usage: WTAU time
The decay constant for the waveshifting fiber in nano-seconds (default 12.0).

RMIR card

Usage: RMIR mirror_reflectivity
The reflectivity of the mirrored end of the waveshifting fiber. This is a value in the range 0 to 1 (default 0.70).

BSAT card

Usage: BSAT saturation_coeff
This is the satturation coefficient of the scintillator (cf. difls_1cell.F). The default value is 13.3.

Not yet active


select event generator, vertex selector methods, limit beam radius. ...not yet in place ... soooooon!


WFLUK related

Usage: WFTZSHIFT tzshift
Apply (or not) the WFLUK flux reweighting and tell the function what target shift was used.

VERT card

Usage: VERT i
Originally used to limit events to iron, concrete and/or active detectors. Needs to be re-thought in new scheme.

EPIO card

MOCK card
Last modified: Thu Jul 5 18:53:56 CDT 2007