Previous Up Next
4 Running WHIZARD
4.1 Setting up the process list
WHIZARD is able to cope with arbitrary scattering processes allowed by the selected physical model. The program is not a library of processes, but the user can compile a list of processes he is interested in, write a file whizard.prc and put it in the subdirectory conf. If no file is provided by the user, the file whizard.prc.default (Fig. 1) will be used. The user may take this file as a template, insert or delete processes as desired, and save the new version as whizard.prc.9 
# WHIZARD configuration file

# The selected model
model   SM

# Processes
#  Methods: chep=CompHEP, mad=MadGraph, omega=O'Mega, test=trivial)
#  Options: s      selected diagrams (CompHEP/MadGraph)
#           r      restricted intermediate state (O'Mega)
#           c      apply exact color algebra (O'Mega)
#           n:XXX  coupling order (MadGraph)
#           w:XXX  width scheme (O'Mega)
#           p      transfer polarization (test)
#           u      unit matrix element (test)
#
# Tag           In      Out             Method  Option
#=====================================================
ee_c            e1,E1   e1,E1           chep
ee_m            e1,E1   e1,E1           mad
ee_o            e1,E1   e1,E1           omega
ww_c            e1,E1   W+,W-           chep
ww_m            e1,E1   W+,W-           mad
ww_o            e1,E1   W+,W-           omega
zh_c            e1,E1   Z,H             chep
zh_m            e1,E1   Z,H             mad
zh_o            e1,E1   Z,H             omega
nnh_c           e1,E1   n1,N1,H         chep
nnh_m           e1,E1   n1,N1,H         mad
nnh_o           e1,E1   n1,N1,H         omega
nnbb_m          e1,E1   n1,N1,b,B       mad
nnbb_o          e1,E1   n1,N1,b,B       omega

Figure 1: Default process configuration file

4.1.1 Model selection
WHIZARD is not restricted to the Standard Model. The physics model is selected in the header of whizard.prc, respectively.

For each model, all particles, parameters, and the vertices which go into the phase space setup are defined in a single file with extension .mdl. The vertex definitions include the complete specification of Feynman rules for MadGraph and CompHEP, while the O'Mega vertices are currently hard-coded in the corresponding executable. The model files can be found in the conf/models subdirectory. Along with the master files SM.mdl, MSSM.mdl, etc., for each model XXX there is also a file parameters.XXX.omega.f90 which contains the translation to the parameter definitions used internally by O'Mega.

The distribution contains the following models (see Tab. 2):
Model type with CKM matrix trivial CKM
QED with e,µ,t,g -- QED
QCD with d,u,s,c,b,t,g -- QCD
Standard Model SM_CKM SM
SM, all unitary gauge SM_ug_CKM SM_ug
SM with anomalous couplings SM_ac_CKM SM_ac
MSSM MSSM_CKM MSSM

Figure 2: Summary of models currently supported by WHIZARD.

Since version 1.51, there are also the following models available: These models are not fully tested yet and are subject to change in future versions. To make them available, O'Mega version 000.011 or higher has to be installed with these models enabled. CompHEP or MadGraph matrix elements for these models are not supported.

The user might wonder whether this list can be extended. Actually, it is trivial to set up, e.g., a SM version with a different input parameter scheme or different particle naming conventions, etc.: Copy SM.mdl to, e.g., SM_new.mdl, make the changes in that file, and provide copies of the corresponding files for use of the matrix element generators. Furthermore, by writing the Feynman rules into a Lagrangian file, one may easily modify or set up a new model for CompHEP, which then can be used by WHIZARD. Modifying the model for O'Mega requires changing program sources, however. The same holds for MadGraph, if you are interested in Lorentz or Dirac structures that are not present in the SM.

4.1.2 Process list
WHIZARD is capable of computing 2-> n scattering processes and 1-> n decay processes. In the former case, the overall result (the integral) displayed by the program will be the total cross section in fb. In the latter case, it will be the partical decay width in GeV.

For scattering processes, n=1 (single-particle production) is allowed1011. Obviously, this requires at least one beam to be structured, such that a continuous energy spectrum is available for the initial state.

Each process is defined by a single line in whizard.prc, for instance: 
h_production    e1,E1   n1,N1,H         chep
z_decay         Z       e1,E1           omega
z_production    e1,E1   Z               omega
(see Fig. 1). The meaning of the entries within a line is as follows:

The first entry is a unique alphanumeric tag which will be used to identify the process. It can be arbitrarily chosen, but should be a valid Fortran 95 token, lower case only. In particular, one may use lower-case characters and digits as well as the underscore, where the first character is not a digit.

The second entry defines the initial state. It consists of two particle names, separated by a comma, with no space in between. The particle names are those given in the model file mentioned above, where typically for each particle several possible names are listed. As an example, in Fig. 3, the Standard Model particles are displayed as they appear in SM.mdl. This file also contains alternative names, quantum number assignments, and the physical parameters of the model.
Particle Name Antiparticle Mass Width
d-quark d D    
u-quark u U    
s-quark s S ms  
c-quark c C mc  
b-quark b B mb  
t-quark t T mtop wtop
electron e1 E1 me  
muon e2 E2 mmu  
tau-lepton e3 E3 mtau  
e-neutrino n1 N1    
µ-neutrino n2 N2    
t-neutrino n3 N3    
gluon G      
photon A      
Z-boson Z   mZ wZ
W-boson W+ W- mW wW
Higgs H   mH wH

Figure 3: Particle names (CompHEP naming scheme) and parameters for the Standard Model.

The third entry defines the final state. It consists of two or more particle names, separated by commas, with no space in between.

Flavor sums (available only for O'Mega matrix elements) are defined by particle names separated by colons. For instance, the line 
  eeqq  e1,E1   u:d:s,U:D:S     omega
will create a sum of all processes e-e+-> qq_, with q being any of the light quarks. Similarly, 
  qqmm  u:d:s,U:D:S   e2,E2     omega
creates a sum of all processes qq_-> µ-µ+. This is especially suitable for hadronic collisions. One should note that the mirror process q_q-> µ-µ+ is not automatically included. To get the correct results for a hadron collider, one can either double cross section values and symmetrize final-state distributions12 (for a symmetric initial state, e.g. pp) or define the process as13 
  qqmm u:d:s:U:D:S,u:d:s:U:D:S e2,E2 omega
Note that in the diagnostics messages at runtime, only a single flavor assignment will be shown, which is used as a template for generating phase space parameterizations. For the matrix element evaluation and event generation, however, all valid flavor assignments are used.

To make this more readable, there is the possibility to specify aliases: The above definition is equivalent to 
  alias  q  u:d:s:U:D:S
  qqmm   q,q   e2,E2    omega
Alias definitions can be arbitrarily mixed with process definitions. They are applied consecutively to all in- and out-state specifications below their definition.

The particles to be summed over must have identical spin, mass and color representation; otherwise the summation will not work. This feature is therefore useful mainly for summing over fermions with identical quantum numbers (quarks or leptons).

The order of particles in the final state can matter if PYTHIA/JETSETis used for fragmenting events. If no information on color connections is available in simulated events (in the current implementation, this holds for CompHEP and for O'Mega matrix elements if the 'c' option is not set), the (dominant) color configuration has to be inferred from the particle ordering, if at all possible. CompHEP, unfortunately, reorders particles according to its own conventions. To transfer the color connections to JETSET, particles that make up a color-singlet string should be put together, beginning with the quark, possibly intermediate gluons, and ending with the antiquark. This suffices for well-defined flavor states. If flavor sums are used (O'Mega) and more than one quark pair is present, all possible orders of particles will show up in the final state.

The fourth entry selects one of the three programs CompHEP, MadGraph, O'Mega  or the test module for matrix element generation. Many processes can be treated by more than one package, allowing for cross-checks, but there are limitations: The fifth entry is either absent or consists of a string of code letters separated by commas (blanks in between are allowed). Some code letters are followed by a colon ':' that indicates a value. The letters specify certain options for matrix element generation:
4.2 Compilation and installation
After the processes have been selected, the matrix elements and executable code are compiled and linked by the simple command
make prg
This will generate an executable named whizard in the bin subdirectory.

An alternative is
make bundle
which will create a restricted bundle containing the Fortran 95 source code of the selected matrix elements and the libraries which have not been explicitly disabled.15 This bundle will be put as a gzipped tar file in the main directory under the name whizard-bundle-XXX.tgz, where XXX specifies the current date and time. The bundle can be unpacked on a different platform. There, it can be configured, compiled and run without the need for a working O'Mega installation. The configuration and input files (whizard.prc, whizard.in, etc.) will be copied from the conf directory of the distribution (not from the results directory). The site-specific configuration config.site will not be copied (precisely because it is site-specific). The restricted bundle has all capabilities of the WHIZARD system except for the possibility to re-generate the matrix elements.

If only the source code for the process list should be generated, say
make proc-src
The files can be found in the subdirectory processes-src. If desired, the source code can be modified before a further make call compiles and links them together.

A run of the Monte Carlo generator requires, apart from the executable, the following input and configuration files. In their initial form they are found in the conf subdirectory: When the command
make install
is issued, all necessary configuration files, together with the whizard executable, are copied into the results subdirectory. If no user-defined files are found, default ones will be used. The contents of the results directory may be copied anywhere without affecting the functionality of the whizard executable within, leaving room for the simultaneous use of multiple WHIZARD copies with different process content. ('make install' implies 'make prg', so the latter is in fact redundant.)

Alternatively, one can omit the install step and copy the WHIZARD executable to any place in the system, or just leave it in the bin subdirectory. For a successful run of WHIZARD, one needs, of course, copies of the input files in the working directory.

Dealing with compilation problems
Although the author has tried to make the program compile and run in various environments, it may happen that something goes wrong. The following problems are, at least, known: In any case, whether you could not solve a configuration or compilation problem or you found a workaround, please contact the author
wolfgang.kilian@desy.de
so that the issue can be dealt with in a future release. (Please make sure that you are running the most recent version of WHIZARD, or at least look in the current CHANGES file whether a bug has been fixed in the meantime.)

4.3 Process selection
For running WHIZARD, the user can freely choose among the processes he has defined in the configuration file and compiled in the executable. The parameter process_id in the main input file (see below) is a string which contains the list of process tags, e.g. 
  process_id = "zh, zz, zw"
If there is more than one process, integration of the cross sections will be performed in sequence. If a subsequent simulation step is requested, the events will be mixed according to their relative total cross sections. If fragmentation is enabled, one can even mix WHIZARD processes with processes generated by PYTHIA (see Sec. 4.8).

Since the integration grids are written to separate files, they can be reused later if events are to be simulated for the same or a different collection of processes, provided the input parameters and cuts are identical. This may save a lot of adaptation and integration time.

If the parameter process_id is left empty, WHIZARD will just print the list of processes, write a logfile containing the complete parameter list (including user settings), and exit.

4.4 Input data
When the whizard executable is started, it will use the parameters from the copy of the file whizard.in in the working directory. In this file, the physical input parameters and runtime switches are set. There are very many parameters, and all of them are optional. WHIZARD will try to insert sensible default values if the user has not specified a value. Of course, if no process tag is given, WHIZARD can do nothing, so it will just display the list of processes and exit.

The file whizard.in is written using the Fortran 95 NAMELIST conventions. It consists of several blocks marked by a keyword beginning with the & character and closed by a slash /. Each block contains a list of assignments of the form variable = value. Variables left out are assigned their default value. The assignments are separated by commas or newlines. Whitespace can be inserted anywhere. Comments can be inserted in this file; they begin with ! and extend up to the end of the line.

An example for the input file is shown in Fig. 4. In many cases, it suffices to fill the process_input block and leave all others empty. If polarization, beamstrahlung etc. are intended, the beam_input blocks must also be considered.

As an alternative to the NAMELIST format, WHIZARD supports the SUSY Les Houches Accord format for its input file. See Sec. 4.4.7 for details. 
 &process_input
 process_id = "nnh"
 sqrts = 500
 luminosity = 100
 /

 &integration_input
 calls = 
   1  10000
   5  10000
   2  20000
 /

 &simulation_input
 write_events = T
 /

 &diagnostics_input /

 &parameter_input
 Me = 0
 Ms = 0
 Mc = 0
 MH = 115
 wH = 0.3228E-02
 /

 &beam_input 
 /

 &beam_input 
 /

Figure 4: Sample input file.

4.4.1 Files
The process_input block allows to specify a generic filename. This can be used to organize WHIZARD run data by giving specific filenames. For instance, to indicate the process energy in the filename for all output files, one may write 
&process_input
 process_id = "nnh"
 sqrts = 800
 filename = "whizard_800"
/
Then, the output files will be whizard_800.out and whizard.800.nnh.out, etc. You do not need to write a separate file whizard_800.in, however: if a specific file is not found, the program will always look for the default one, in this case whizard.in.

Similarly, the working directory can be specified by the directory parameter. Of course, the first input file to be read must reside in the initial directory, otherwise it cannot be found (unless you define it on the command line, see Sec. 5.6).

The filename setting is overridden by specific filenames such as input_file or phase_space_file. Such filenames will be interpreted relative to the chosen directory (if set), unless they begin with a slash, e.g., 
  read_model_file = "/home/whizard/standard_model/whizard"
or with ``./'', e.g., 
  read_model_file = "./whizard"
The latter form refers to the initial working directory. Note that in all cases the filename extension (here, .mdl) will be appended to the filename you specify.

It is possible to specify an additional input_file name in the process_input block. This input file will be read after the current one. New settings of parameters override old ones. In principle, any number of input files can be read consecutively and merged in this way. Reading input is finished when an input file does not exist, or neither directory nor input_file is changed in the last reading. Obviously, one should avoid loops in file reading.

All external file names used by WHIZARD can be similarly redefined. As a special rule, the filename for reading something (cuts, grids, events etc.) will automatically be set equal to the corresponding filename for writing, unless it is specified explicitly. The reason is that those files will be rewritten if the corresponding input file is not found, which could lead to accidentally overwriting files which is not intended.

4.4.2 The process_input block
These parameters should always be inspected.
Parameter Value Default Description
process_id string empty Process tag(s) as defined in whizard.prc. It should contain the list of processes to activate, separated by commas or blanks, enclosed in quotes.
cm_frame T/F T If true, the c.m. frame is the lab frame, the beams are in ± z directions, and the total c.m. energy is given by sqrts. If false, the beam energies and directions must be specified below in the blocks beam_input.
sqrts number 0 If this number is greater than the sum of the incoming particle masses, it specifies the c.m. energy of the initial state in GeV. Applies only if cm_frame is true, and is ignored for decay processes.
luminosity number 0 Integrated luminosity in fb-1. A nonzero value will activate event generation. (Alternatively, the number of events can be specified below in the block simulation_input.) The luminosity value is ignored for decay processes.
polarized_beams T/F F If true, the helicity content of the beams must be specified below in the blocks beam_input.
structured_beams T/F F If true, the nature of the incoming beams must be specified below in the blocks beam_input.
beam_recoil T/F F If true, and if structure functions (e.g., ISR) are selected, the recoil of the partons against the beam remnant (e.g., the emitted photons) is taken into account. The pT distribution is computed within the approximation valid for the emission, hence it will be accurate at low pT.
recoil_conserve_momentum T/F F Applies only if beam_recoil is set: if true, keep momentum balance between parton and recoil momenta at the expense of energy balance. If false, keep energy balance at the expense of momentum balance.
filename string empty Base filename (w/o extension) to be used for all input/output files instead of the string "whizard".
directory string empty Working directory for all further reading/writing of files.
input_file string empty If nonempty, read the specified input file after the current one. The extension .in will be appended to the filename.
input_slha_format T/F F If true, assume that the next input file is in SUSY Les Houches Accord format (see Sec. 4.4.7). If false, determine the format from the first line.

4.4.3 The integration_input block
These parameters will not affect the cross section value (with the possible exception of the default cut parameters) but can improve or disprove the running time, the stability and accuracy of the result, and the efficiency of event generation.
Parameter Value Default Description
calls 6 numbers (yes) Array describing the number of iterations and number of calls per integration pass. Default values depend on the selected process. See below in subsection 4.6 for details.
seed integer undefined Random number generator seed (integer). When omitted, the time counter will be used, resulting in a different value each run.
reset_seed_each_process T/F F Reset the random number generator seed to seed not just once, but each time a process is integrated. This is useful for comparing matrix elements which should be identical, but, e.g., have been generated by different programs.
accuracy_goal number 0 Goal for the accuracy estimate (6th column in the output). When this goal is reached and the efficiency goal is either also reached or unset, further grid adaptation iterations will be skipped (Sec. 4.9).
efficiency_goal percentage 100 Goal for the reweighting efficiency estimate (7th column in the output). When this goal is reached and the accuracy goal is either also reached or unset, further grid adaptation iterations will be skipped (Sec. 4.9).
time_limit_adaptation integer 0 If nonzero, grid adaptation for the current process will be stopped after the specified number of minutes, and the final integration pass started (Sec. 4.9).
stratified T/F T Use stratified (T) / importance (F) sampling.
use_efficiency T/F F Use efficiency (T) / accuracy (F) as the criterion for adapting the channel weights.
weights_power number 0.25 Power used for adapting the channel weights. Lower value means slower adaptation (to suppress fluctuations).
min_bins integer 3 Minimal number of bins per integration dimension.
max_bins integer 20 Maximal number of bins per integration dimension. This number will be used as long as there are enough sampling points, otherwise the number of bins will be decreased.
min_calls_per_bin integer 10 Minimal number of points per bin, integration dimension, and integration channel. If this limit cannot be satisfied, the total number of points will be increased.
min_calls_per_channel integer 0 All integration channel will get at least (approximately) this number of points. Prevents channels from being dropped during adaptation.
write_grids T/F T Write grids to files whizard.grb (best grid) and whizard.grc (current grid), to be reused later.
write_grids_raw T/F F Use binary format for writing grids. Saves memory at the expense of portability.
write_grids_file string empty If nonempty, use the specified filename for writing grids instead of the default. The file extensions are appended to string.
write_all_grids T/F F Write, in addition, after each iteration the current grid to file whizard.grXXX, where XXX is the iteration number.
write_all_grids_file string empty If nonempty, use the specified filename for writing the extra grids instead of the default. The file extensions are appended to string.
read_grids T/F F Read existing grids whizard.grb and whizard.grc if they have been written by a previous run. This avoids the time-consuming adaptation step. Makes sense only if no physical parameters have been changed.
read_grids_raw T/F F If true, search first for binary grid files, then for ASCII grids. If false, do search first for ASCII..
read_grids_force T/F F Set this to T if you want to read the grids from file even if some parameters have changed. Use with care! This may result in a program crash if the grid structures are incompatible.
read_grids_file string empty If nonempty, use the specified filename for reading grids instead of the default. The file extensions are appended to string.
generate_phase_space T/F T Generate a phase space configuration appropriate for the current process and write it to whizard.phx.
read_model_file string empty If nonempty, read vertex definitions for phase space setup from string.mdl instead of the default whizard.mdl.
write_phase_space_file string empty Write phase space configuration to string.phx instead of the default.
read_phase_space T/F T Read phase space configuration from whizard.phs or a previously generated file whizard.phx if possible.
read_phase_space_file string empty Read phase space configuration from string.phs or string.phx instead of the default.
phase_space_only T/F F Stop the program after phase space generation.
use_equivalences T/F T If true, use permutation symmetry when updating grids to improve the quality of the results.
azimuthal_dependence T/F F If false, it is assumed that the scattering does not depend on the overall azimuthal angle. This will be automatically T if general beam polarization is switched on, therefore the user need only access this parameter in the case of azimuthal-dependent cuts.
write_phase_space_graphs_file string empty Show phase space diagrams in string.ps instead of the default file whizard-graphs.ps

The following parameters affect the details of the algorithm by which WHIZARD generates the phase space setup. Under normal circumstances, there should be no need to change them.
Parameter Value Default Description
off_shell_lines integer 1 Maximum number of off-shell-lines allowed for Feynman graphs which are initially taken into account for the phase space configuration. Log-enhanced (massless) propagators are not counted as off-shell.
extra_off_shell_lines integer 1 Use configurations with more off-shell lines, if they happen to be maximally resonant.
splitting_depth integer 1 Up to this number of branchings, a (massless) propagator will be considered as log-enhanced and mapped like a photon propagator.
exchange_lines integer 3 Up to this number of t-channel propagators, a multiperipheral graph will be taken into account.
show_deleted_channels T/F F With extra_off_shell_lines, extra channels will be generated which are deleted if they do not contain enough resonances. With this flag, they are just commented out, so they could be manually activated.
single_off_shell_decays T/F T Whether single-off-shell decays are relevant for the phase space configuration.
double_off_shell_decays T/F F Whether double-off-shell decays are relevant for the phase space configuration.
single_off_shell_branchings T/F T Whether single-off-shell branchings are relevant for the phase space configuration.
double_off_shell_branchings T/F T Whether double-off-shell branchings are relevant for the phase space configuration.
massive_fsr T/F T Whether the radiation of a massive particle in the final state is relevant for the phase space configuration.
threshold_mass number 50 A particle with a mass up to this value will be considered as massless for the purpose of phase-space setup. (But the true mass is taken into account when the particle appears as a resonant intermediate state.)
threshold_mass_t number 200 A particle with a mass up to this value will be considered as massless for the purpose of phase-space setup, when it appears as a t-channel propagator.

The following parameters affect the setup of kinematical cuts. Note that the default cuts are taken into account only if there is no appropriate entry in the user cut file whizard.cut1. However, even if such an entry exists, the cut parameters below affect the phase-space mappings, so adjusting them to order-of-magnitude may improve the convergence of the result.
Parameter Value Default Description
default_jet_cut number 10 The default invariant mass cut in GeV applied to pairs of massless colored particles.
default_mass_cut number 10 The default invariant mass cut in GeV applied to pair production of massless colorless charged particles and to photon emission.
default_energy_cut number 10 The default energy cut in GeV applied to photon and gluon emission.
default_q_cut number 10 The default Q cut in GeV applied to photon and gluon exchange.
write_default_cuts_file string file If nonempty, write the list of default cuts to this file (augmented by the file extension) instead of the default. Note that the settings in this file are overwritten by a user-defined cut configuration, if present.
read_cuts_file string empty Look for user-defined cut configurations in string.cut1 instead of whizard.cut1.
user_cut_mode integer 0 Set this nonzero to activate a user-defined cut function (Sec. 5.4).
user_weight_mode integer 0 Set this nonzero to activate a user-defined weight function (Sec. 5.5).

4.4.4 The simulation_input block
These parameters control event generation, hadronization and output. If the luminosity (above) is left undefined or zero, one may still generate a fixed number of events by setting n_events nonzero. By default, the events are written to file in raw format and can be reused in that way. Writing events in another format (which uses up more disk space) must be requested explicitly. However, if this has not been done, one may use WHIZARD afterwards as a translator to any file format by reading pre-generated events and immediately writing them in another format: 
&integration_input  read_grids = T /
&simulation_input   read_events = T  write_events = T /
Parameter Value Default Description
n_events integer 0 Number of (unweighted) events to generate at least, irrespective of the luminosity setting.
n_calls integer 0 Number of matrix-element calls (weighted events) to execute at least, irrespective of the luminosity setting.
n_events_warmup integer 0 Number of extra warmup events (see below, Sec. 4.7).
unweighted T/F T Reweight events to generate an unweighted event sample.
normalize_weight T/F T If true, normalize the event weight to unity. If false, normalize to the total cross section.
write_weights T/F F If unweighted=F, write weight distribution data to whizard.wgt.
write_weights_file string empty Write weight distribution to string.wgt instead.
safety_factor number 1 Multiply the estimate for the highest weight by this factor before starting event generation.
write_events T/F F Write generated events to file whizard.evt to be used by an external analysis package.
write_events_format integer 1 The format to be used for writing events, where the file extension depends on the format (.evt for format = 1, see Sec. 4.7).
write_events_file string empty If nonempty, use string as filename for writing events, where the file extension will be appended.
events_per_file integer 0 If positive, begin a new event file once the number of entries exceeds this number. The event file counter is appended to each event file name, separated with a dot (before the file extension).
bytes_per_file integer 0 If positive, begin a new event file once the number of bytes in the file exceeds this number. The event file counter is appended to each event file name, separated with a dot (before the file extension). This feature applies only to the machine-readable formats (HEPEVT, SHORT, LONG, STDHEP). See Sec. 4.7.1.
min_file_count integer 1 If event files are split, use this index for the first event file. Increase the counter by one for each successive event file.
max_file_count integer 999 Limit for the event file counter; if this limit is exceeded, event generation is terminated. (For weighted events only, this is an error condition since the event sample must be complete for being usable.)
write_events_raw T/F T Write events to whizard.evx in condensed binary format, so they can be internally reused in another run.
write_events_raw_file string empty Write raw events to string.evx instead.
read_events T/F F Read events from file whizard.evx (raw format) instead of generating them. This is equivalent to read_events_raw.
read_events_force T/F F Read events from file even if some parameters have changed. Use with care!
read_events_raw_file string empty Read raw events from string.evx instead.
keep_beam_remnants T/F F Keep the beam remnants in the event record when applying structure functions. See Sec. 4.4.8.
keep_initials T/F F Keep the beam particles and the partons which initiate the hard scattering in the event record. See Sec. 4.4.8.
guess_color_flow T/F F Infer the color flow for hadronization from the particle ordering, if it is nontrivial and not available directly.
recalculate T/F F Recalculate the matrix element value for each event of a previously generated sample. Setting this flag automatically turns on reading grids and events from file.
fragment T/F F Fragment the events depending on the value of fragmentation_method (see Sec. 4.8).
fragmentation_method integer 1 Method used for fragmentation if fragment is true: 0=no fragmentation; 1=JETSET; 2=PYTHIA; 3=user.
user_fragmentation_mode integer 0 When user-defined fragmentation routines are called, this parameter may select different modes.
pythia_parameters string empty String to be given to PYTHIA's pygive call before starting event generation. This allows to modify PYTHIA/JETSET properties, set particle masses, etc. The string is also available within user-defined fragmentation routines and can there be abused for different purposes.
pythia_processes string empty PYTHIA background processes to be simulated in addition to the WHIZARD processes: A list of integers separated by blanks, enclosed in quotation marks. Refer to the PYTHIA manual for the list of processes.

4.4.5 The diagnostics_input block
These parameters do not affect the result, but the information displayed on screen and stored in files.
Parameter Value Default Description
chattiness integer 4 How much information to show on screen: (0) only fatal errors, (1) and non-fatal errors, (2) and warnings, (3) and messages, (4) and results, (5) and debugging messages (if any).
catch_signals T/F T If the compiler supports it, try to catch external signals such as SIGINT and SIGXCPU and exit gracefully, closing files first.
time_limit integer 0 If nonzero, exit gracefully after the given number of minutes has passed. This is useful to prevent an external kill within a batch environment.
warn_empty_channel T/F F Issue a warning whenever the integral within a phase space channel is zero.
screen_events T/F F Whether to show generated events on screen.
screen_histograms T/F F Whether to show histograms on screen.
screen_diagnostics T/F F Whether to repeat the input parameters on screen.
show_pythia_banner T/F T Whether to display the PYTHIA banner page if fragmentation is enabled.
show_pythia_initialization T/F T Whether to display the PYTHIA initialization messages if fragmentation is enabled.
show_pythia_statistics T/F T Q Whether to display the PYTHIA statistics summary after event generation is completed.
write_logfile T/F T Whether to write the output file(s) whizard.XXX.out.
write_logfile_file string empty Use this as the filename for the logfile.
show_input T/F T Whether to repeat the input parameters in the logfile.
show_results T/F T Whether to show the integration results in namelist format in the logfile.
show_phase_space T/F F Whether to show the phase space configuration in the logfile.
show_cuts T/F T Whether to show the cut configuration in the logfile.
show_histories T/F F Whether to show the individual VAMP channel histories in the logfile.
show_history T/F T Whether to show the overall VAMP history in the logfile.
show_weights T/F T Whether to show the weight adaptation in the logfile.
show_event T/F F Whether to show the last event in the logfile.
show_histograms T/F F Whether to show histograms in the logfile.
show_overflow T/F F Whether to show events beyond the first or last bin in histogram listings.
show_excess T/F T Whether to show a summary of events with weight exceeding one.
read_analysis_file string empty Use this as the filename for the analysis setup instead of whizard.cut5
plot_width number 130 The width in mm of the plots if online analysis is enabled.
plot_height number 90 The height in mm of the plots if online analysis is enabled.
plot_excess T/F T In the plots, display excess events in red.
plot_history T/F T If this is enabled, write a graphics driver file for displaying the integration history, i.e., the integral with error bars for each iteration. Use make history to generate the graphics file whizard-history.ps.
plot_grids_channels string empty The string is a list of phase-space channels (integers) for which the bin distribution will be histogrammed. Use make grids to generate the graphics file whizard-grids.ps.
plot_grids_logscale number 10 Use logarithmic scale for the grid plots if the bin width varies over more than this ratio.
slha_rewrite_input T/F T If SUSY Les Houches Accord data have been used, whether to repeat this input in the process-specific logfiles (including comments) or to rewrite it there using the data which have actually been used.
slha_ignore_errors T/F F If this is false, an error signaled in the SLHA input file (in the SPINFO or DCINFO block) will cause WHIZARD to stop before calculating anything. If true, such errors will be displayed, but the run continues.

4.4.6 The parameter_input block
These are the physical constants used in evaluating the matrix elements. If this block is left empty, default values (see below) will be inserted.

Which constants are actually present, and which ones are dependent or derived, depends on the physical model. Consult the model files in conf/models for the corresponding parameters. For example, the constants relevant for the Standard Model SM_CKM are shown below together with their default values:
Parameter Value Default Description
GF number 1.16639× 10-5 Fermi constant
mZ number 91.1882 Z-boson mass
mW number 80.419 W-boson mass
mH number 200 Higgs mass
gg number 1.218 Strong coupling constant as(MZ)
s12 number 0.221 CKM matrix parameter (PDG)
s23 number 0.040 CKM matrix parameter (PDG)
s13 number 0.0035 CKM matrix parameter (PDG)
me number 0.000511 electron mass
mmu number 0.1057 muon mass
mtau number 1.777 t-lepton mass
ms number 0.12 s-quark mass
mc number 1.25 c-quark mass
mb number 4.2 b-quark mass
mtop number 174 t-quark mass
wtop number 1.523 t-quark width
wZ number 2.443 Z-boson width
wW number 2.049 W-boson width
wH number 1.419 Higgs width
The dependent parameters (such as e, sinqW, Vcb etc.) will be shown in the output file whizard.out, but one should not try to reset them in the input file. The dependencies take into account the tree approximation only, such that gauge invariance is automatically respected. This may lead to unwanted side-effects in particular cases, e.g., the Higgs coupling to b quarks is proportional to the b mass, so setting mb=0 removes all H-> bb_ subprocesses.

Setting fermion masses to zero will considerably speed up the matrix element evaluation since certain helicity combinations vanish identically (with MadGraph and O'Mega). In that case, cuts may be needed for a finite answer. However, if necessary, finite masses can be kept for all particles except the light quarks u and d.

Concerning quark masses in particular, they depend in fact on the chosen scale. The default values for the parameters include the strong coupling constant defined at the scale µ=MZ, but the quark masses evaluated at the low scale µ=2 GeV. These default values are taken from the PDG 2000 compilation. For a consistent scheme, running quark masses should be inserted instead wherever this is of importance. For instance, the b mass is only about 2.9 GeV at µ=MZ, thus affecting the Higgs coupling to b quarks.

Although they can be calculated from the other parameters in principle, the particle widths are retained as independent input parameters. Thus, the branching ratio of a particular resonance decay can be tuned by modifying the resonance width. When the Higgs mass is changed, the Higgs width has to be changed accordingly if Higgs decays are considered. The default values for the particle widths are given by the sum of the tree-level 1-> 2 decay channels, using the default masses and couplings as input. This choice is questionable as well. Since O'Mega, MadGraph and CompHEP can only calculate cross sections at tree level, this is at least consistent; however, for each particular problem one should re-investigate the underlying assumption that 2-particle decays are dominant, and recalculate the widths accordingly. This cannot (yet) be done by WHIZARD.

Finally, even if a parameter is defined and appears in the output, this does not necessarily mean that its value is used by all three programs CompHEP, MadGraph and O'Mega. For instance, the CKM matrix is currently taken into account only by the CompHEP version of the Standard Model.

There are two switches within the parameter_input block:
Parameter Value Default Description
gwidth T/F F Use the gauge-invariant width prescription for unstable particles in CompHEP matrix elements. This is the so-called overall factor scheme. For O'Mega, the corresponding 'f' option has to be specified in the process configuration file already.
rwidth T/F F Use a running-width prescription for unstable particles in CompHEP matrix elements.

4.4.7 Input in SUSY Les Houches Accord format
The SUSY Les Houches Accord (SLHA) [10] describes a format to pass MSSM physics data between computer programs. WHIZARD accepts its input file in SLHA format. This requires that either It is possible to In this way, several input files in both formats may be read consecutively, which could be useful to set defaults and override some parameters computed by a SUSY spectrum calculator. However, the recommended procedure is to supply a standard whizard.in file where the process selection, collider information, and WHIZARD switches and runtime parameters are set, while containing all physical data in a separate file written in SLHA format which is read afterwards. The latter may be produced by an automatic spectrum and decay calculator.

In the output, if SLHA data have been used, the data will be repeated. WHIZARD reorders the blocks, where the blocks that actually have been used (which may include MODSEL, SMINPUTS, MINPAR, MASS, and mixing data) come first. The parameter slha_rewrite_input in the diagnostics_input block controls whether the input data are just copied into the output (preserving all comments, but not necessarily the ordering of blocks) or rewritten by WHIZARD. In the latter case, the relevant parameters in the output are made consistent between the standard WHIZARD format and the SLHA format, where applicable. Furthermore, for each process a block PROCESS will be appended which contains the integration results in a format which follows the SLHA conventions. The block CSINFO (cross section calculator information) is added, analogous to the SPINFO and DCINFO blocks described in the standard (see Fig. 5). 
 ! Begin SLHA data
# SUSY Les Houches Accord Version 1.0
Block MODSEL  # Select model
    1    1    # mSugra
Block SMINPUTS   # Standard Model inputs
    1   1.279340000e+02  # alpha_em^(-1)(MZ)
    2   1.166370000e-05  # G_Fermi
    3   1.172000000e-01  # alpha_s(MZ)MSbar
    4   9.118760000e+01  # MZ(pole)
    5   4.250000000e+00  # Mb(mb)
    6   1.743000000e+02  # Mtop(pole)
    7   1.777000000e+00  # Mtau(pole)
:
# WHIZARD: The following blocks have not been used:
Block EXTPAR          # non-universal SUSY breaking parameters
:
# WHIZARD: The following blocks have been added:
BLOCK PROCESS   # Result of cross section calculation
    1          2         # Number of incoming particles 
    2         11         #   Incoming particle: e               
    2        -11         #   Incoming particle: a-e             
   11          3         # Number of outgoing particles 
   12         12         #   Outgoing particle: nu_e            
   12        -12         #   Outgoing particle: a-nu_e          
   12         25         #   Outgoing particle: h               
   21    8.64682817E+01  # Cross section in fb
   22    2.13675042E-01  # Cross section error in fb
   23    2.30119652E-02  # Chi-squared value
# 
BLOCK CSINFO   # Cross section calculator information
    1    WHIZARD    # Calculator name
    2    1.28       # Calculator version
# 
 ! End SLHA data

Figure 5: Sample output in SLHA format

WHIZARD will use the MASS and DECAY information in the SLHA file to set the physical masses and widths of the particles it recognizes. Branching ratio information is not used. Note that the masses of some SM particles (Z, t, b, and t) are defined in SMINPUTS. For completeness, they may also be set in the MASS block (where the W mass is located). If the values disagree, the MASS information takes precedence for WHIZARD's needs. The widths of Z, W, and t may be set using the DECAY format. In all cases, default values (which may have been set in a previous input file) will be taken without warning where data are missing.

While the SLHA is intended for the MSSM and its extensions, it is possible to use this format to pass physical parameters for a SM calculation. If the SM is chosen when configuring WHIZARD, only the blocks MODSEL, SMINPUTS, MASS and DECAY information will be used. By convention, we define the model parameter (in the MODSEL block) to be negative for a non-SUSY model.

4.4.8 The beam_input blocks

The input file is finished by two blocks which describe the properties of the first and second incoming particle beam, respectively. It depends on the master flags in the process_input block above whether particular information within these blocks is actually used: If all of the master flags are kept at their default values, the content of the beam_input blocks is completely discarded, so they may be left empty.

For decay processes, there are some obvious restrictions: There is only one ``beam'', so the second block is ignored. While cm_frame and polarized_beams retain their meaning (i.e., one can simulate the decay of a moving and/or polarized particle), structured_beams is ignored, and no structure functions can be selected.

Energy and direction
If the master flag cm_frame is false, the beam energies and directions are set by
Parameter Value Default Description
energy number 0 If greater than the beam particle mass, this specifies the beam energy in the lab frame. Otherwise, the beam energy is set equal to the particle mass (fixed target).
angle number 0 If direction is not set, this specifies a rotation of the beam axis in the lab frame around the positive y axis. (By default, the beam directions are along the positive/negative z axis, so a rotation by the angle p/2 turns them into the positive/negative x axis.) If direction is set, this parameter is ignored.
direction three numbers 0 0 0 If any component is nonzero, this vector explicitly specifies the direction of the given beam in the lab frame.

Polarization
If the master flag polarized_beams is true, the polarization is set for each beam by
Parameter Value Default Description
vector_polarization T/F F If false (default), use the standard helicity basis (left-/right-handed). Set this flag if you need another basis, in particular transversal polarization.
polarization two (three) numbers 0 0 0 Fraction of left/right polarization (fermions, photons, gluons), resp. left/longitudinal/right polarization (massive vector bosons). If the vector polarization model is selected, the three numbers denote the polarization vector.
For fermions, the default (helicity basis) polarization model describes longitudinally polarized beams with the specified fraction of left- and right-handed particles. In the case of massless vector bosons, this corresponds to left and right circular polarization along the beam axis. Massive vector bosons have three entries, where the middle entry specifies the fraction of longitudinal polarization. If the numbers sum up to less than 1, the remainder is filled with unpolarized particles. For instance, .5 0 and .75 .25 both stand for 50 % left-handed polarized electrons.

The quantization axis of a polarized particle is the momentum vector in the lab frame. For particles at rest, the quantization axis is the positive z axis.

The vector polarization model currently applies to fermions only. The three numbers denote the components of a three-vector P® with length less or equal to 1. The helicity density matrix for fermions is given by
r = 12(1 +
®
P
 
·
®
s
 
),     (5)
where the polarization vector has components (Px,Py,Pz). For antifermions this is replaced by
r = 12(1 +
®
P
 
·
®
s
 
*),     (6)
so the y component changes sign.

While the z component of P® describes longitudinal polarization, the x and y components correspond to transversal polarization. Longitudinally polarized states can therefore be specified in both polarization models, while transversal polarization requires the vector model.

Spectra and structure functions
If the master flag structured_beams is true, WHIZARD will check if any of the structure functions defined below is applicable for this beam. For each beam, the beam particle is defined by either one of
Parameter Value Default Description
particle_code integer 0 PDG code of the incoming beam particle.
particle_name string "UNKNOWN" Name of the incoming beam particle.
If both entries are specified, the given PDG code takes precedence.

The further parameters specify which structure functions are used for each beam and fix structure function parameters where necessary. Structure functions are applied consecutively (Tab. 1), choosing a sensible chain of beam particle splittings: For instance, if the beam particle is an electron and the process is initiated by a quark, switching on both EPA and PDF will take the quark content of a photon which is emitted (in the Weizsäcker-Williams approximation) by the incoming electron. WHIZARD will not check whether the selected combination makes physically sense.

If it is desired to have the beam remnants in the event record, one should set keep_beam_remnants in the simulation_input block. The beam remnants will be photons (beamstrahlung, ISR), charged particles (EPA) or undefined hadron remnants (PDF). A beam remnant is always massless, regardless which mass the corresponding particle has been assigned somewhere else, and it will have no transverse momentum. There will be exactly one beam remnant per structure function even though the number of photons radiated in beamstrahlung and ISR is not well-defined in reality. Beam remnants cannot be used for the built-in analysis since they are assigned no binary codes. Their main virtue is to make possible a reconstruction of individual splittings in the initial state in an external analysis.

Furthermore, one can set keep_initials. In that case, the beam particles and the partons which initiate the hard scattering are kept in the beam record. Together with the beam remnants, this allows for full mother-daughter relationships to be displayed. For fixed-energy beams, there are no beam remnants, and the initial partons are identical with the beam particles.
Structure function in-particle out-particle user beam pol.
File events any = in keep
User spectrum (Sec. 5.3) any any keep/ignore
CIRCE (beamstrahlung) e± e± keep
  e± g ignore
CIRCE2 (beamstrahlung) e±/g e±/g ignore
ISR (photon radiation) charged particle unchanged keep
EPA (effective photon approximation) charged particle g ignore
PDF (parton distribution functions) p,p_ or g q or g ignore
User structure function (Sec. 5.3) any any keep/ignore

Table 1: Available structure functions. Each transform an in-particle into a collinear out particle with a certain momentum fraction. They may be concatenated in the order given in the table. In the present implementation, the user-specified beam polarization is either kept unchanged for all events, or is overwritten.

Events from file
WHIZARD is able to read a sample of events from file and use it for integration and event generation. If both beams are read from file in this way and the filename is identical for both beams, the program expects a pair of real numbers in each line of the file. (Otherwise, it expects separate files with a single real number per line.) Each number corresponds to the energy carried by the beam particle. Empty lines and comment lines (marked by # or !) are skipped.

When the end of the beam event file is reached, a warning is issued and the file is reread from the beginning. Note that reusing the event sample in this way leads to systematic errors in the calculation. For instance, the fluctuations of the computed cross section between subsequent iterations can exceed the error estimate by orders of magnitude. In the final integration step, this could be visible as a c2 value which is anomalously large. To avoid this problem, it is recommended to use an event sample which is statistically distributed and contains a sufficient number of events so that no rewinding is necessary.
Parameter Value Default Description
FILE_events_on T/F F Whether to read the beam events from file.
FILE_events_file string empty File name. The directory prefix (as specified by directory above, if any) will be prepended and the extension .bev will be appended to this string. If this file does not exists, the default file whizard.bev is searched instead.
FILE_events_energies T/F T Whether the numbers in the file should be interpreted as absolute energies (T) or as energy fractions with respect to the nominal beam energy, i.e., s1/2/2 in the c.m. frame (F).

Beamstrahlung (CIRCE1)
For beamstrahlung, the accelerator type should always be defined, and it is not recommended to use an energy different from the values for which valid CIRCE [6] parameterizations exist. There is the option to either use the generator mode of CIRCE, or to accept the distributions calculated by CIRCE as analytical spectra. For efficiency reasons, the generator mode is typically preferred.
Parameter Value Default Description
CIRCE_on T/F F Whether to apply beamstrahlung (electron, positron or photon beam).
CIRCE_generate T/F T Whether to use the CIRCE event generator or the analytical beamstrahlung spectra.
CIRCE_map T/F T Whether to apply a mapping to improve convergence (relevant for analytical spectra only).
CIRCE_sqrts number s1/2 The reference energy. Note that CIRCE spectra are defined only for discrete energy values.
CIRCE_ver integer 0 The CIRCE version number required.
CIRCE_rev integer 0 The CIRCE revision number required.
CIRCE_acc integer 0 The accelerator type as needed by CIRCE.
CIRCE_chat integer 0 The level of CIRCE diagnostics.

Photon spectra (CIRCE2)
CIRCE2 is intended as a replacement for CIRCE1. While the previous implementation provided smooth spectra, the new version, which has to be used for photon collider spectra where no CIRCE1 version is available, provides histogrammed spectra which are read from a data file. These data files are currently not contained in the WHIZARD distribution. Sample data files can be retrieved from the CIRCE2 website:
http://heplix.ikp.physik.tu-darmstadt.de/lc/beam.html
There is the option to either use the generator mode of CIRCE2, or to accept the distributions calculated by CIRCE2 as (histogrammed) spectra. For efficiency reasons, the generator mode is typically preferred.

The following parameters can be defined (identical for both beams):
Parameter Value Default Description
CIRCE2_on T/F F Whether to use CIRCE2 for simulating spectra.
CIRCE2_generate T/F T Whether to use the CIRCE2 generator or the (histogrammed) spectra.
CIRCE2_verbose T/F T Whether to print CIRCE2 messages on screen.
CIRCE2_file string empty The data file to read by CIRCE2.
CIRCE2_design string "*" The accelerator design for CIRCE2.
CIRCE2_polarized T/F T Use a polarized (T) or polarization-averaged (F) spectrum in the datafile.
CIRCE2_map -1/0/1 -1 Apply a power mapping for a singularity at x=0 or x=1, or no mapping (-1). Relevant only for histogrammed spectra, irrelevant for the CIRCE2 generator mode.
CIRCE2_power number 2 Parameter for the mapping, if any.
If CIRCE2 is switched on, the CIRCE2_file parameter must always be given. The filename will be interpreted relative to the current working directory. The accelerator design should be specified if the data file contains more than one dataset. (The default matches the last dataset within the data file.)

It is important to note that polarization treatment is different from the standard WHIZARD conventions when CIRCE2 is used. The CIRCE2 data files introduce fixed polarization distributions of the beams which originate from realistic simulations. Therefore, the polarized_beams switch and the polarization settings should not be used together with CIRCE2 under normal circumstances. Instead, the appropriate data file with polarization should be taken and CIRCE2_polarized switched on. This will generate the appropriate polarized spectra, properly normalized.

On the other hand, if a polarization-averaged dataset is specified, CIRCE2_polarized should also be switched off.

Despite the fact that the polarization distributions are a fixed property of any given dataset, one can reweight the polarization contributions by hand. To this effect one can set polarized_beams and polarization. For instance, by switching on only one helicity combination, the properties of the corresponding cross section component can be studied. This feature should be used with care, since the results may be unphysical.

In the spectra mode (CIRCE2_generate=false), if no mapping is specified by the user, the program inserts a mapping at x=0 (power = 3) for photons, and a mapping at x=1 (power = 12) for electrons. This assumes that all particles originate from an incident e- beam, where for electrons there is a strong singularity (in fact, a smeared-out delta function) at x=1. For a different setup, e.g., a positron beam, the mapping parameters have to be adjusted by hand. Note that without the x=1 mapping, the delta-function singularity for electrons will almost certainly be missed by the adaptive integration, and the result may stabilize for a wrong cross section.

ISR spectrum
The ISR spectrum for charged particles accounts for the leading-logarithmic effect of multiple photon emission. In the leading-logarithmic approximation, universal terms of order en with e=a/plns/m2 can be absorbed in a structure function. The leading singularity at x=1 can be calculated exactly, while the other terms of the structure function are known only to finite order.

The implementation in WHIZARD takes into account the LLA structure function ([7]), including terms up to order en, where n=0,1,2,3, depending on the value of ISR_LLA_order. The default value is n=3. The scale which enters the ISR spectrum is given by ISR_scale; the default is to take the collider c.m. energy.

Since aQED is usually calculated from GF as far as the hard scattering is concerned, it makes sense to reset it to 1/137 here. The incoming particle mass (e.g, me) must be defined here only if it has been set to zero in the parameter input block (e.g., to speed up the calculation).
Parameter Value Default Description
ISR_on T/F F Whether to apply ISR (electron or positron beam).
ISR_alpha number e2/4p The value of aQED to be used for the spectrum.
ISR_m_in number m The mass of the incoming particle.
ISR_scale number s1/2 The hard scale which cuts off photon radiation.
ISR_LLA_order 0/1/2/3 3 The order of the leading-logarithmic approximation.
ISR_map T/F T Whether to use a mapping of the singularity at x=1 when evaluating the structure function (recommended).

EPA spectrum
The EPA spectrum is the Weizsäcker-Williams approximation for a real photon radiated off the incoming beam. Here, Qmax and mX must be supplied, the other parameters are optional. (If the produced system is massive, mX should be set equal or less to the mass sum of all produced particles.)
Parameter Value Default Description
EPA_on T/F F Whether to use the EPA spectrum (photon beam).
EPA_map T/F T Whether to apply a mapping to improve convergence.
EPA_alpha number e2/4p The value of aQED to be used for the spectrum.
EPA_m_in number m The mass of the incoming beam particle.
EPA_mX number 0 The lower cutoff for the produced invariant mass.
EPA_Q_max number 0 The upper cutoff on the virtuality of the photon (Qmax>0).
EPA_x0 number 0 The lower cutoff on the energy fraction of the incoming photon
EPA_x1 number 1 The upper cutoff on the energy fraction of the incoming photon

Parton distribution functions
Parton distribution functions inside hadrons are accessed by the standard library of parton distribution functions (PDFLIB). Distribution functions exists for all quarks and for the gluon. The parameters are listed below (for a more detailed description, refer to the PDFLIB manual). For the numerical parameters, a zero value will cause the PDFLIB default value to be taken, so only PDF_on and PDF_scale (if PDF_running_scale is false) are mandatory.
Parameter Value Default Description
PDF_on T/F F Whether to use PDFs.
PDF_ngroup integer 0 Number of author group. If left 0, the PDFLIB default value (MRS) will be used.
PDF_nset integer 0 Number of the structure function set by the given group. If left 0, the PDFLIB default value will be used.
PDF_nfl integer 0 Number of active flavors.
PDF_lo integer 0 Order of as calculation.
PDF_running_scale T/F F Whether to use a running scale (the total partonic invariant mass) for the structure function evaluation.
PDF_scale number 0 If PDF_running_scale is false, this parameter must be set to a fixed energy scale for the structure function evaluation.
PDF_QCDL4 number 0 QCD scale in GeV for four active flavors.

4.5 Cuts
WHIZARD allows for cuts in some standard kinematical variables. Cuts may be necessary in case the matrix element is infinite without them (which happens if massless particles are either exchanged or produced). In this case, WHIZARD will apply default cuts on the invariant mass of colored or charged particle pairs, on the energy of emitted photons or gluons, and on the momentum transfer to exchanged photons or gluons. The values of those cuts are controlled by parameters in the input file (see above). 
! e-  e+  ->  e-  e+  gamma
! 16   8       1   2    4
process eeg
  cut Q of 10 within -99999 -1
  cut Q of 17 within -99999 -1
  cut M of  3 within 10 99999
  cut E of  4 within  5 99999
  cut PT of 4 within 19 99999
  cut THETA(DEG) of  4 1 within 5 180
  cut THETA(DEG) of  4 2 within 5 180

Figure 6: Cut configuration file

Alternatively, the user may specify his own set of cuts by supplying an entry in the file whizard.cut1. If such an entry exists, the program will ignore the default cuts, and the user is responsible for setting up his cuts in such a way that the cross section is still finite. The format of such an entry for the process e-e+-> e- e+ g is shown in Fig. 6. The contents of whizard.cut0, where the default cuts are logged by WHIZARD (if any), may be used as a template.

The entry is begun by the keyword process followed by the process tag (eeg in this case). If the same set of cuts should be applied to several processes, one may specify more than one tag per entry, e.g. 
process uudd uuss uucc
    cut ...
The cut configuration file may contain any number of process entries. Comments are marked by the letter ! or #.
Code Alternative code(s) # Args Description
-   0-2 No cut
M Q 1 (Signed) invariant mass M=sgn(p2)|p2|1/2
LM LQ 1 log10 |M|
MSQ QSQ S T U 1 Squared invariant mass M2 = p2
E   1 Energy in the lab frame
LE   1 log10E
PT   1 Transverse momentum p^
LPT   1 log10 p^
PL   1 Longitudinal momentum pL
P   1 Absolute value of momentum |p®|
Y RAP RAPIDITY 1 Rapidity y
ETA   1 Pseudorapidity h
DETA DELTA-ETA 2 Pseudorapidity distance Dh
PH PHI 1 Azimuthal angle f (lab frame) in radians
PHD PHID PHI(DEG) 1 Azimuthal angle f (lab frame) in degrees
DPH DPHI DELTA-PHI 2 Azimuthal distance Df (lab frame) in radians
DPHD DPHID DELTA-PHI(DEG) 2 Azimuthal distance Df (lab frame) in degrees
AA ANGLE-ABS TH-ABS THETA-ABS 1 Absolute polar angle qabs (lab frame) in radians. Reference axis is the z-axis.
AAD ANGLE(DEG)    
  TH-ABS(DEG) THETA-ABS(DEG) 1 Absolute polar angle qabs (lab frame) in degrees
CTA COS(TH-ABS) COS(THETA-ABS) 1 cosqabs
A ANGLE TH THETA 2 Relative polar angle q (lab frame) in radians
AD ANGLE(DEG)    
  TH(DEG) THETA(DEG) 2 Relative polar angle q (lab frame) in degrees
CT COS(TH) COS(THETA) 2 cosq
A* ANGLE* TH* THETA* 2 Relative polar angle q* (rest frame of part.#2) in radians
AD* ANGLE*(DEG)    
  TH*(DEG) THETA*(DEG) 2 Relative polar angle q* (rest frame of part.#2) in degrees
CT* COS(TH*) COS(THETA*) 2 cosq*
DR DELTA-R CONE 2 Distance in h-f space, i.e. Dh2 + Df21/2
LDR LOG-DELTA-R LOG-CONE 2 log10Dh2 + Df21/2

Table 2: Cut and histogram code letters. Masses, energies and momenta are measured in GeV.

For a given process, each cut is indicated by the keyword cut, followed by a code letter, the keyword of, one or two binary codes, and cut window specifications. The code letters are listed in Table 2. The binary codes indicate the combination of particle momenta to which the cut should be applied. As the comment lines in Fig. 6 suggest, the outgoing particles are given codes 1,2,4,.... Two additional codes are assigned to the incoming particles, where the first incoming particle has the highest number. Momentum sums (particle combinations) are defined by adding binary codes, such that the code 5, for instance, stands for the sum of momenta of particles 1 and 4.

The initial momenta are always counted negative, such that (in Fig. 6) the number 17 stands for the difference of the momenta of particle 1 (outgoing) and 16 (incoming). The same applies to angles: The polar angle between 1 and 16 is not A of 1 16 but A of 1 8 since the initial particle 16 goes into the direction of -p(8).

By default, the inserted momenta are those of the elementary partonic process. Thus, one can assume momentum conservation. For instance, in a 2-> 2 scattering process, the invariant mass of 1+2=3 (the outgoing particles) is the same as the invariant mass of 4+8=12 (the incoming particles). In some circumstances, one may need the incoming beam momenta instead. To insert those in place of the incoming parton momenta, use a negative number. In the previous example, the invariant mass of -12 would be the invariant mass of the incoming beams which is equal to the nominal c.m. energy. Of course, there is no difference unless the process is a 2-> n scattering process with structure functions enabled.

Cut window specifications consist of the keyword within and two real numbers, optionally followed by additional specifications like 
  cut PT of  4 within 0 150
  cut M  of  3 within 80 100 or 180 200 or 500 99999
The absence of an upper bound should be marked by a number outside the kinematical range.

4.6 Integration
4.6.1 Running WHIZARD
After the input parameters and cuts have been specified, the integration can be started by 
make run
or, if we are in the working directory (results), 
./whizard
After each iteration, the result will be displayed on screen and logged in the file whizard.XXX.out, where XXX is the process tag. An example is shown in Fig. 7. As it is expected, the integration converges towards a stable result, and at the same time the estimated reweighting efficiency increases (allowing for some fluctuations). 
 ! WHIZARD 1.30 (Sep 20 2004)
 ! Reading process data from file whizard.in
 ! Wrote whizard.out
 ! Process nnbb_m:
 !    e a-e -> nu_e a-nu_e   b a-b
 !   32  16 ->    1      2   4   8
....
 !=============================================================================
 ! WHIZARD run for process nnbb_m:
 !-----------------------------------------------------------------------------
 ! It      Calls   Integral[fb]  Error[fb]  Err[%]    Acc  Eff[%]   Chi2 N[It]
 !-----------------------------------------------------------------------------
 ! Reading cut configuration data from file whizard.cut1
 ! No cut data found for process nnbb_m
 ! Preparing (fixed weights):   2 samples of      10000 calls ...
    1      20000  5.8943963E+01  1.10E+00    1.86    2.63*  1.74    0.83   2
 !--------------------------------------------------------------------------
 ! Adapting (variable wgts.):   8 samples of      10000 calls ...
    2      10000  5.7221665E+01  1.15E+00    2.01    2.01*  5.72
    3      10000  5.9627610E+01  6.79E-01    1.14    1.14* 10.31
    4      10000  5.9342736E+01  5.98E-01    1.01    1.01* 12.49
    5      10000  5.8460284E+01  5.48E-01    0.94    0.94* 10.81
    6      10000  5.8342202E+01  5.32E-01    0.91    0.91* 13.79
    7      10000  5.8022785E+01  5.10E-01    0.88    0.88* 13.23
    8      10000  5.8170899E+01  4.99E-01    0.86    0.86* 15.10
    9      10000  5.7867127E+01  4.84E-01    0.84    0.84* 16.91
 !--------------------------------------------------------------------------
 ! Integrating (fixed wgts.):   2 samples of      10000 calls ...
   10      20000  5.7669248E+01  3.37E-01    0.58    0.83* 14.43    0.02   2
 !--------------------------------------------------------------------------

Figure 7: Sample output of running WHIZARD.

The number of iterations and the number of calls per iterations are as given in the input file whizard.in (see Fig. 4). Adaptation proceeds in three passes which are separated by a horizontal line in the output:

In the first integration pass, the grids are adapted after each iteration, but the relative weight of the integration channels is kept fixed. In the example of Fig. 7, this pass consists of two iterations with 10,000 calls each. This pass is useful in particular for many-particle processes, where it takes some time before VAMP has found the physical region in each channel.

In the second pass, the grids within each phase space channel and the relative weights of the phase space channels are adapted after each iteration. The example of Fig. 7 shows how the integral converges, the error estimate improves, and the estimated reweighting efficiency increases, until some saturation is reached. Here, the sixth column is of main interest, which is given by the estimator for the relative error multiplied by the square root of the number of calls. One expects a number of the order of unity (or smaller) here for a well-adapted grid, independent of the number of calls. Each time this number improves, it is marked by an asterisk. The best grid will be used later for the final integration and event generation steps.

In the third pass, the relative weights are fixed again, and the remaining iterations are averaged for the final cross-section result.

4.6.2 The phase space configuration
The critical point for the integration is the phase space configuration. This is set up automatically by WHIZARD before starting the integration. When integrating a given process for the first time, a phase space configuration is generated and written to the file whizard.phx. In subsequent runs for the same process, this file is reused. If you would like to edit and modify this file or if you want to set up your own configuration, the new configuration should be stored in the file whizard.phs which takes precedence over whizard.phx and will not get overwritten. The automatically generated file whizard.phx will be deleted when the process list changes or, in any case, by a make clean command.

For each process, WHIZARD phase space consists of a set of channels which formally correspond to Feynman diagrams. In the automatically generated phase space configuration file whizard.phx, these channels are listed in order, using binary codes for the internal lines. The graphs that have been generated can be drawn and viewed on screen or printed:
make graphs
This generates a LATEX file whizard-graphs.tex which uses the FeynMF package for drawing Feynman graphs, and transforms it into a PostScript file whizard-graphs.ps. These files are located in the results directory. Note that this is currently available only for the automatically generated phase space, not for a phase space setup supplied by the user.

Similarly, the bin distributions of the grids as they have been adapted during the WHIZARD run can be converted into histograms by
make grids
and viewed as the file whizard-grids.ps.

It should be kept in mind that the choice of phase space channels does not influence the integration results (all Feynman graphs are included in the cross section calculation and event generation, but for the phase space setup only some of them are used --- and some are even used twice). However, the accuracy and the speed of convergence depend on this choice. In many cases it will not be necessary to modify anything, but if you are not satisfied with the results of the default configuration, the following remarks may help. The number of channels in the default configuration tends to be somewhat too large. Many channels turn out to be irrelevant and will be dropped during the self-adaptation procedure. If you can guess which ones those are, you may use the available parameters and options for manual intervention to optimize the channel selection. As an example, the effective Zee coupling is almost zero because of sin2qw~ 1/4, so graphs with Z emission from electron lines are suppressed. You could remove such graphs, either manually, or by removing the Zee vertex from the whizard.mdl file before starting the program. (You have to be careful not to drop resonant Z-> ee decays, then.) However, in most cases, while this may save some running time for the adaptation, it is not worth the effort.

On the other hand, it may happen that important channels are missed by the default configuration. In this case, the restrictions should be weakened.

4.6.3 What if it does not converge?
Although WHIZARD is able to produce stable results with the default settings for a large variety of scattering processes, it is not possible to guarantee fast convergence of the cross section estimate in all circumstances. There is no simple rule for the achievable accuracy and event generation efficiency for a given process; the examples in Sec. 6 should provide some guideline. In any case the screen output of the adaptation procedure should be inspected, and questionable results should not be used for simulation.

Experience shows that in well-behaved 2-> 4 processes an accuracy (Err/Exp in the output) below 1 and an estimated reweighting efficiency above 10 % is reasonable. Due to the increased dimensionality of phase space, for 2-> 6 processes the numbers are typically worse by a factor 2 to 4.

If convergence is apparently not reached, i.e., there are sizable fluctuations in the result, this may be due to one of the following causes:
4.6.4 Output files
All results are logged in a generic file whizard.out and in process-specific files whizard.XXX.out, where XXX is the process tag. The output files are rewritten after each iteration. Depending on the settings of the diagnostics parameters, they will contain additional information: The contents of the input file are repeated, including also the default values which have been inserted by the program. Furthermore, it shows the detailed history of the individual integration channels and of their relative weights.

After each iteration, the current VAMP grids are written to file as well: whizard.XXX.grc for the current grid and whizard.XXX.grb for the best grid. These may be reused in another run.

4.7 Event generation

4.7.1 Unweighted events
Event generation is activated in the input file, either by specifying a nonzero luminosity 
&process_input
...
luminosity = 100
/
or by a nonzero number of events 
&simulation_input
n_events = 10000
/
In the former case, the actual number of generated events depends on the calculated cross section. If both numbers are given, the one leading to the larger event sample will be used. It is also possible to specify n_calls, which is the number of matrix element calls. However, this is more useful for weighted event samples (see below).

The simulation makes sense only if WHIZARD could find a stable result for the cross section. This should be judged from inspecting the results displayed on screen and in the log file whizard.out.

With event generation activated, WHIZARD will not stop after the integration step, but start event generation. By default, WHIZARD will generate unweighted events, which result from reweighting the events produced by the VAMP sampling algorithm. In the event generation step, importance sampling is used, such that the events are random and have the proper distribution as required for a realistic simulation.

WHIZARD is able to write events to file in various formats: Note that the formats that require external libraries (PYTHIA, STDHEP) do not work if the corresponding libraries have not been linked to the main program.

Within each event, the particles will appear in the order determined by the process definition (for MadGraph and O'Mega; CompHEP may reorder them). Hadronization packages such as JETSET require a particular order of colored particles to properly assign showers, it be may necessary for the user to rearrange them before feeding them into the hadronization step. In general, if color-flow information is absent (for O'Mega and CompHEP matrix elements), one may set guess_color_flow to tell the program that the particles are to be combined as singlets in the order in which they appear in the event record.

Reweighting Monte-Carlo events requires the knowledge of the highest weight. This can never be known with certainty in advance, so there may be some fraction of events with weight greater than one. By default, WHIZARD will sum up the excess weight of those events and show the induced error in the total cross section, which should be small compared to the statistical error of event generation. If desired, the excess events can be further analyzed by WHIZARD's own analysis capabilities (see below), to make sure that they have no significant impact on final results. By setting the safety_factor in the simulation_input block to a number greater than one, the amount and weight of excess events (if any) will be reduced. However, the time needed for event generation will be increased by the same factor.

WHIZARD will use the adaptation step to determine the highest weight beforehand. This requires sufficient statistics in the adaptation procedure. If many events have to be generated, the default choice for the number of calls per iteration may be too low, and too many excess events are produced. As a rule of thumb, the number of calls per adaptation iteration should be of the order of the number of unweighted events divided by the estimated efficiency.

Alternatively, a ``test'' run can be made by specifying a nonzero value of n_events_warmup in the input file. For instance, one may generate 200,000 (weighted) events to determine the highest weight before generating the actual sample to be used for the reweighting procedure: 
&simulation_input
n_events = 10000
n_events_warmup = 200000
/
Fortunately, this is not necessary in most cases since the pre-determined highest weight is usually quite accurate. 
  integer, parameter :: nmxhep = 4000
  integer :: nevhep, nhep
  integer, dimension(nmxhep) :: isthep, idhep
  integer, dimension(2, nmxhep) :: jmohep, jdahep
  real(kind=double), dimension(5, nmxhep) :: phep
  real(kind=double), dimension(4, nmxhep) :: vhep
  common /HEPEVT/ nevhep, nhep, isthep, idhep, &
       & jmohep, jdahep, phep, vhep

Figure 8: Definition of the HEPEVT common block in Fortran 95 format

       WRITE(22, 11, IOSTAT=ICHEK) NHEP
       DO I=1,NHEP
          WRITE (22, 13, IOSTAT=ICHECK) ISTHEP(I),IDHEP(I), &
        &               (JMOHEP(J,I),J=1,2), (JDAHEP(L,I),L=1,2)
          WRITE (22, 12, IOSTAT=ICHECK) (PHEP(J,I),J=1,5)
          WRITE (22, 12, IOSTAT=ICHECK) (VHEP(L,I),L=1,5)
       END DO

 11    FORMAT(1I5)
 12    FORMAT(10F17.10)
 13    FORMAT(I9,I9,4I5)

Figure 9: Equivalent FORTRAN77 code which would produce the event file whizard.evt from the contents of a HEPEVT common block.

write(u,11) evt%n_out + evt%n_beam_remnants, &
     &      evt%n_out, evt%n_beam_remnants, weight
do i=1, evt%n_out
   p = array(particle_momentum(evt%prt(i)))
   write (u,13) particle_code(evt%prt(i)), evt%hel_out(i)
   write (u,12) p(1:3), p(0), particle_mass(evt%prt(i))
end do
11 format(1I5,1X,F17.10)
12 format(10F17.10)
13 format(I9,I9,5I5)

Figure 10: Output routine for the SHORT event file format. Note that the number of beam remnants and the event weight are not part of the HEPEVT standard.

write(u,11) evt%n_out + evt%n_beam_remnants, &
     &      evt%n_out, evt%n_beam_remnants, weight
do i=1, evt%n_out
   p = array(particle_momentum(evt%prt(i)))
   write(u,13) particle_code(evt%prt(i)), evt%hel_out(i)
   write(u,12) p(1:3), p(0), particle_mass(evt%prt(i))
end do
write(u, 12) evt%mc_function_value, evt%mc_function_ratio
11 format(3I5,1X,F17.10)
12 format(10F17.10)
13 format(I9,I9,5I5)

Figure 11: Output routine for the LONG event file format. Note that the number of beam remnants and the event weight are not part of the HEPEVT standard.

write(u,11) evt%count, event_n_entries (evt)
k = 0
do i=1, evt%n_out
   k = k + 1
   p = array(particle_momentum(evt%prt(i)))
   write (u,13) k, 1, particle_code(evt%prt(i)), &
        & evt%n_in+1, 2*evt%n_in, (0, j=1,2)
   write (u,12) p(1:3), p(0), particle_mass(evt%prt(i))
   write (u,12) (0._default, j=1,4)
end do

Figure 12: Output routine for the ATHENA event file format. (If the initial particles and/or the beam remnants are to be kept, these are written before the outgoing particles.)

write (u,16) nup, idprup, xwgtup, scalup, aqedup, aqcdup
write (u,17) idup(:nup)
write (u,17) mothup(1,:nup)
write (u,17) mothup(2,:nup)
write (u,17) icolup(1,:nup)
write (u,17) icolup(2,:nup)
write (u,17) istup(:nup)
write (u,17) ispinup(:nup)
do i=1, nup
   write (u,18) i, pup((/4,1,2,3/),i)
end do

Figure 13: Output routine for the Les Houches Accord event file format.

4.7.2 Weighted events
The default setup will generate unweighted events, which is the proper way of simulating actual physics runs. The cross section error of the simulation run is equal to the square root of the number of events, as it should be.

This requires an unweighting step where, depending on the ratio of the current event's weight and the maximum weight, a large fraction of the generated event sample is thrown away. Clearly, information is lost in this step. To keep all available information, one can use weighted events instead: 
&simulation_input
unweighted = F
...
/
The number of weighted events is calculated such that (approximately) the same unweighted event sample would result from unweighting them afterwards, as it would from directly generating unweighting events. If luminosity or n_events do not require a higher number, the total number of weighted events generated is approximately equal to n_calls.

If there is more than one process, the luminosity is distributed among them proportional to the individual cross sections. In contrast to unweighted generation, the events are ordered, such that all events belonging to the first process are generated first, then the next one, and so on. The exact number of weighted events for a given process depends on both the cross section and the efficiency. For a process with low efficiency, a larger number of weighted events is needed for the same cross section than for a high-efficiency process. (In unweighted event samples, the individual event numbers depend only on the cross sections.)

These events can also be written to file and analyzed by an external program. For each event, the event weight is a number between zero and one (if no excess events are present), and it is printed as the last number in the first line of the output. Hence, in this definition the weight is the probability with which the event would have been kept in the sample if an unweighting step had taken place. As a result, differential (binned) distributions should be identical for weighted and unweighted event samples, apart from fluctuations.

Unfortunately, the HEPEVT standard does not allow for event weights. Therefore, the PYLIST and STDHEP output formats which read out the HEPEVT common block cannot be used for weighted events. By contrast, event weights can be transferred using the HEPEUP common block, so the STDHEP_UP format does work for weighted events. Keep in mind that weighted events are ordered, so files containing those must not be truncated or extended.

4.7.3 Built-in analysis
WHIZARD has capabilities to analyze the events without reference to external packages. To this end, a configuration file whizard.cut5 should be set up which has a similar format as whizard.cut1. For instance, in Fig. 14 a configuration file is shown which tells WHIZARD to analyze the generated event sample in three different ways: to calculate the cross section within a window 80<M(e+e-)<100, then within 180<M(e+e-)<200 with an additional cut on p^(g), and finally to generate a histogram of p^(e-) with a cut on the photon energy. 
! e-  e+  ->  e-  e+  gamma
! 16   8       1   2    4
process eeg
  cut M of 3 within  80 100
and
  cut M  of 3 within 180 200
  cut PT of 4 within 100 99999
and
  cut E of 4 within 0 100
  histogram PT of 1 within 0 500

Figure 14: Analysis configuration file.

The histogram specification may take either one of the form 
histogram PT of 1 within 0 500
histogram PT of 1 within 0 500 nbin 50
histogram PT of 1 within 0 500 step 10
Instead of the number of bins (20 by default), the bin width can be specified by the keyword step.

The cross section results are displayed on screen. In addition, they are written together with the histogram data to the file whizard-plots.dat. If show_excess=T has been set in the input file, the summary and the histograms will contain also information about any events with weight greater than one, such that their properties can be examined.

Clearly, for a quick analysis it is not necessary to simulate proper unweighted events. Therefore, one may set unweighted=F in order to analyze a sample of weighted events, which saves a lot of execution time.

The contents of whizard-plots.dat can be visualized directly by means of the gamelan graphical analysis package which is contained in the distribution. This requires the existence of the MetaPost program, which is part of standard LATEX distributions. Plots can then be made by typing 
make plots
This will result in a Postscript file whizard-plots.ps which can be viewed and printed.

The event sample can further be analyzed in terms of color flow, helicity and flavor content. Example 
! e-  e+  ->  q  qbar  b  bbar
! 16   8      1   2    4   8
process qqbb
  cut M of 3 within 85 95
  color 0 0 4 0 6 0
  helicity  1 -1 -1 1
  helicity -1  1 -1 1
  flavor    2 -2 5 -5
  histogram M of 12 within 0 500
This would plot a histogram of the invariant mass of the bb_ pair with the additional requirement that the other quark pair must be uu_, that the b (anti)quarks must be left- resp. right-handed, and that the uu_ and bb_ pairs are each in a color-singlet state.17

Color flow is defined in a natural way: The particles are numbered consecutively beginning from the initial ones (do not confuse this with the binary codes used for specifying cuts and histograms). For an incoming quark or gluon, the index of the particle its color flows to is given, while for an outgoing quark or gluon it is the index of the particle its color comes from. (This differs from WHIZARD's internal convention where incoming and outgoing particles are equally treated, but it is easier to use.) For colorless particles and for antiquarks, the entry is zero. So, in the above example, the q color comes from the q_, and the b color from the b_.

Helicities and flavors are indicated as usual: Fermions and massless vector bosons have helicity ± 1, massive vector bosons can come with helicity 0 in addition, and for scalars the helicity is always zero. Flavor is denoted by standard PDG codes.

The order should be as in the above example: first cut specifications (the event must pass all cuts), then color, helicity and flavor specifications (the event must match any of the given helicity combinations and any of the given flavor combinations), finally histogram specifications. Any of these may be absent; an empty entry will just display the total cross section again. More analysis configurations can be added for the same process, they must be separated by the keyword and.

4.8 Fragmentation

The Les Houches standard [9] for transferring events together with weight and color information allows for a consistent interface of partonic event generators and programs that account for showering, fragmentation, and hadronization. In order to use such an external program, WHIZARD has to write events to file in a format that supports this information. Currently, there is the LHA format (code: 5) that writes, for each event, the contents of the HEPEUP block in ASCII format, and the STDHEP_UP format (code: 21) that writes this information into a portable binary STDHEP file. The first record of this file will contain the HEPRUP common block; then, for each event, the HEPEUP common block is written.

Alternatively, WHIZARD provides an internal interface to routines for fragmentation, decays and hadronization. For each event, WHIZARD calls the corresponding external program that fills the HEPEVT common block and writes this to file. To activate this, the parameter fragment in the simulation_input block must be set to true. Of course, the corresponding library has to be properly linked. Only unweighted events can be fragmented. (This is because the HEPEVT standard does not allow for the event weight to be transferred.)

Once fragment is set, various options are available, depending on the value of the parameter fragmentation_method:
  1. No fragmentation within WHIZARD (for completeness).
  2. JETSET fragmentation. The final state is fragmented and hadronized by a call to the PYEXEC fragmentation routine inside PYTHIA, i.e., by the former JETSET program. If available, color flow information is used (currently, this is possible only with MadGraph matrix elements). Otherwise, the color connection properties of the final state are guessed by JETSET from the particle ordering, which must therefore carefully be chosen by the user when defining the process.
  3. PYTHIA fragmentation. The final state is fragmented and hadronized by making the process generated by WHIZARD an external process within PYTHIA. If possible and depending on the PYTHIA parameter settings, beam remnants are constructed, multiple interactions and pile-up events are added, and more.
  4. This parameter value is intended to transfer control to fragmentation routines written by the user and included in the user module. Of course, such code can make use of the HEPRUP and HEPEUP common block contents. For additional flexibility, there is also a parameter user_fragmentation_mode (integer) that allows for selecting different versions of user fragmentation.
Currently, full color information is available only for MadGraph matrix elements. However, for PYTHIA fragmentation WHIZARD will provide missing color information if can be uniquely determined. Otherwise, it tries to guess color connections from the particle ordering in the event record (just as JETSET does). If color connection information cannot be determined, colored states cannot be fragmented in this way. If fragmentation is nevertheless desired (even though the results may not be accurate), one has to revert to JETSET fragmentation.

No effort is done to streamline WHIZARD and PYTHIA parameters, so changing a value in the WHIZARD input file will have no effect on the fragmentation step. However, PYTHIA parameters can be explicitly set by an interface to PYTHIA's pygive routine. For instance, the line 
  pythia_parameters = "MSTP(41)=0; MSTP(81)=0"
in the simulation_input block disables resonance decays and multiple interactions within PYTHIA. Similarly, the Higgs mass may be set by a call like 
  pythia_parameters = "PMAS(25,1)=115"
The detailed list of parameters available is described in the PYTHIA manual [1].

The internal analysis routines described in Sec. 4.7.3 always refer to the event before fragmentation. To analyze the fragmented event, the user must use an external package.

4.8.1 Parton showers

In the default settings, PYTHIA events are constructed with parton showers developing along colored and charged partons. In WHIZARD, fixed-order matrix elements are evaluated. The matching of both is nontrivial. For this reason, PYTHIA parton showers are disabled in the current WHIZARD version. In a future version, some pragmatic solution may be implemented, e.g., showering with virtualities below the default phase space cutoffs. In general, the availability of exact higher-order matrix elements (albeit tree-level) within WHIZARD makes matching without double-counting a delicate task.

4.8.2 Mixing WHIZARD and PYTHIA events

Since WHIZARD provides an external process to PYTHIA when PYTHIA fragmentation is enabled, it is perfectly possible to mix PYTHIA and WHIZARD events. To this end, one should specify PYTHIA processes in the simulation_input block. For instance, 
  pythia_processes = "22, 24"
will simulate e+e--> ZH and ZZ in addition to the WHIZARD-generated processes. There are some caveats, however:
4.8.3 PYTHIA event display

When fragmentation is enabled, the conventions for writing events to file are changed. The verbose format is then not available since some information (used internally by WHIZARD) is lost after fragmentation. The format codes 1 (HEPEVT), 2 (SHORT), 3 (LONG), and 20/21 (STDHEP) are available. In addition, there are three new format codes (11, 12, 13) which allow for displaying events using PYTHIA's PYLIST call. The respective argument given to PYLIST is 1, 2, or 3, corresponding to three different verbosity levels. (For automatic processing, the more condensed HEPEVT or STDHEP formats are better suited.)

4.9 Controlling WHIZARD runs
For a new process, it is not easy to predict how long it will take to reach a sufficiently precise result or to generate a sufficiently large event sample. The achievable efficiency and accuracy and the overall running time strongly depend on the complexity of the process, the singularity structure of the matrix element and how well WHIZARD is able to map it, the presence or absence of structure functions, and, clearly, the evaluation time of the matrix element for a single event.

Ideally, computer time and space is abundant, one calcaulates cross sections to the highest possible accuracy, and infinitely large event samples are generated. In practice, one does not want to wait too long for useable results, and one is limited by CPU time and space restrictions. Priorities have to be defined. To meet these needs, various switches and levers are available that control WHIZARD runs. All of them are set in the main input file and are listed in the tables of Sec. 4.4.

4.9.1 Grid adaptation

Parameters that control the grid adaptation and integration passes of WHIZARD are collected in the integration_input block in the input file, listed in Sec. 4.4.3

Obviously, the array calls is the principal place for improving the accuracy and efficiency of the adaptation and integration runs. In no case more iterations or calls than specified in calls will be executed, where WHIZARD uses default values for entries left empty by the user.

Increasing the number of adaptation iterations normally improves (decreases) the constant a in the error estimate for the total cross section,
Ds
s
=
a
N
1
2
 
events
,     (7)
until a limit is reached which depends on the matrix element singularity structure and on the choice of phase space integration channels. The estimate for a is printed as the accuracy in the screen output table. Increasing the number of points per iteration tends to decrease the number of iterations needed to reach this limit. In particular, this improves the precision in estimating a and reduces inevitable fluctuations around the ideal grid configuration. Simultaneously the reweighting efficiency e increases, which is the ratio of the average to the maximum event weight. Note that fluctuations in the e estimate are significantly stronger than for a.

If the program has been killed for any reason, it can be restarted with read_grids set, so adaptation is resumed after the last complete iteration. This mechanism can also be used to increase the number of iterations afterwards for a job that has already been completed.

However, one wants to avoid a unnecessary large number of iterations and calls. Adaptation iterations are skipped if any one of the following parameters is set:
accuracy_goal:
If this number is greater than zero, adaptation will stop when the accuracy estimate of the last iteration is smaller.
efficiency_goal:
If this number is greater than zero, adaptation will stop when the efficiency estimate of the last iteration is higher. Note that the efficiency is measured in percent.
time_limit_adaptation:
If this number is greater than zero, adaptation will stop when the real time after the last iteration is later than the specified time limit, measured in minutes from the program start.
In any case, the program will not stop but the third pass (integration) will be executed after the adaptation pass, where the number of integration steps and calls per iteration are taken from the corresponding calls entry.

4.9.2 Simulation

The reweighting efficiency in the final event generation pass is determined by the grid quality, measured by the efficiency e. Since the precision in estimating e is not very high, it may be appropriate to insert a safety_factor f>1 to avoid excess events with weight >1. The time needed for generating a fixed number of unweighted events is then proportional to 1/(fe). As a rule, investing more time in grid adaptation results in a better e value, and thus less time for event generation, up to a certain limit.

The number of unweighted events is specified by either setting n_events in the simulation_input block, or by a luminosity value in the process_input block. The number that leads to a larger event sample will take priority.

If the program is killed during event generation, the event sample is incomplete. The switch catch_signals can be used to catch terminate signals if the OS and compiler supports it, so it is guaranteed the the event files are properly closed before the program terminates. Then, WHIZARD can be restarted with read_events set (which implies read_grids). The events already generated will be reread from the raw event file whizard.evx until the end is reached, and further events will be appended to this file. Event output files in other formats are re-generated on the fly. This method can also be used to increase an event sample afterwards, spending CPU time essentially on newly generated events only.

4.9.3 Hard limits

There are situations where one has to control the amount of memory, CPU time, and disk space which the program uses. In particular, batch installations put limits on these resources and kill processes which exceed them.

Some of these issues can be handled by WHIZARD:
time_limit:
This parameter (in minutes) sets an internal limit on the wallclock time the run may use. When it is exceeded, the program terminates. Depending whether the termination occured during integration or simulation, the program can be restarted such that it will resume after the last grid or event written, respectively.
events_per_file:
This parameter takes care of event files becoming too large: once it is exceeded, a new file is begun. An external analysis would then process the files consecutively. Note that this does not apply to the internal event file whizard.evx which cannot be split; if this file becomes too large, one has to switch it off by write_events_raw=F.
bytes_per_file:
The analogous parameter which counts the number of bytes allowed for an event file. This relies on certain assumptions on the number of bytes an event takes in a particular format.
Previous Up Next