WHIZARD is hosted by Hepforge, IPPP Durham
Previous Up Next

Chapter 3  Getting Started

WHIZARD can run as a stand-alone program. You (the user) can steer WHIZARD either interactively or by a script file. We will first describe the latter method, since it will be the most common way to interact with the WHIZARD system.

3.1  Hello World

The script is written in SINDARIN. This is a DSL – a domain-specific scripting language that is designed for the single purpose of steering and talking to WHIZARD. Now since SINDARIN is a programming language, we honor the old tradition of starting with the famous Hello World program. In SINDARIN this reads simply

The legacy version series 1 of the program relied on a bunch of input files that the user had to provide in some obfuscated format. This approach is sufficient for straightforward applications. However, once you get experienced with a program, you start thinking about uses that the program’s authors did not foresee. In case of a Monte Carlo package, typical abuses are parameter scans, complex patterns of cuts and reweighting factors, or data analysis without recourse to external packages. This requires more flexibility.

Instead of transferring control over data input to some generic scripting language like PERL or PYTHON (or even C++), which come with their own peculiarities and learning curves, we decided to unify data input and scripting in a dedicated steering language that is particularly adapted to the needs of Monte-Carlo integration, simulation, and simple analysis of the results. Thus we discovered what everybody knew anyway: that W(h)izards communicate in SINDARIN, Scripting INtegration, Data Analysis, Results display and INterfaces.

printf "Hello World!"

Open your favorite editor, type this text, and save it into a file named hello.sin.


  | Writing log to 'whizard.log'
  |=============================================================================|
  |                                                                             |
  |    WW             WW  WW   WW  WW  WWWWWW      WW      WWWWW    WWWW        |
  |     WW    WW     WW   WW   WW  WW     WW      WWWW     WW  WW   WW  WW      |
  |      WW  WW WW  WW    WWWWWWW  WW    WW      WW  WW    WWWWW    WW   WW     |
  |       WWWW   WWWW     WW   WW  WW   WW      WWWWWWWW   WW  WW   WW  WW      |
  |        WW     WW      WW   WW  WW  WWWWWW  WW      WW  WW   WW  WWWW        |
  |                                                                             |
  |                                                                             |
  |                                        W                                    |
  |                                       sW                                    |
  |                                       WW                                    |
  |                                      sWW                                    |
  |                                      WWW                                    |
  |                                     wWWW                                    |
  |                                    wWWWW                                    |
  |                                    WW WW                                    |
  |                                    WW WW                                    |
  |                                   wWW WW                                    |
  |                                  wWW  WW                                    |
  |                                  WW   WW                                    |
  |                                  WW   WW                                    |
  |                                 WW    WW                                    |
  |                                 WW    WW                                    |
  |                                WW     WW                                    |
  |                                WW     WW                                    |
  |           wwwwww              WW      WW                                    |
  |              WWWWWww          WW      WW                                    |
  |                 WWWWWwwwww   WW       WW                                    |
  |                     wWWWwwwwwWW       WW                                    |
  |                 wWWWWWWWWWWwWWW       WW                                    |
  |                wWWWWW       wW        WWWWWWW                               |
  |                  WWWW       wW        WW  wWWWWWWWwww                       |
  |                   WWWW                      wWWWWWWWwwww                    |
  |                     WWWW                      WWWW     WWw                  |
  |                       WWWWww                   WWWW                         |
  |                           WWWwwww              WWWW                         |
  |                               wWWWWwww       wWWWWW                         |
  |                                     WwwwwwwwwWWW                            |
  |                                                                             |
  |                                                                             |
  |                                                                             |
  |  by:   Wolfgang Kilian, Thorsten Ohl, Juergen Reuter                        |
  |        with contributions from Christian Speckner                           |
  |        Contact: <whizard@desy.de>                                           |
  |                                                                             |
  |  if you use WHIZARD please cite:                                            |
  |        W. Kilian, T. Ohl, J. Reuter,  Eur.Phys.J.C71 (2011) 1742            |
  |                                          [arXiv: 0708.4233 [hep-ph]]        |
  |        M. Moretti, T. Ohl, J. Reuter, arXiv: hep-ph/0102195                 |
  |                                                                             |
  |=============================================================================|
  |                               WHIZARD 2.4.1
  |=============================================================================|
  | Reading model file '/usr/local/share/whizard/models/SM.mdl'
  | Preloaded model: SM
  | Process library 'default_lib': initialized
  | Preloaded library: default_lib
  | Reading commands from file 'hello.sin'
  Hello World!
  | WHIZARD run finished.
  |=============================================================================|
Figure 3.1: Output of the "Hello world!" SINDARIN script.

Now we assume that you – or your kind system administrator – has installed WHIZARD in your executable path. Then you should open a command shell and execute (we will come to the meaning of the -r option later.)

/home/user$ whizard -r hello.sin

and if everything works well, you get the output (the complete output including the WHIZARD banner is shown in Fig. 3.1)

| Writing log to 'whizard.log'
[... here a banner is displayed]
|=============================================================================|
|                               WHIZARD 2.4.1
|=============================================================================|
| Reading model file '/usr/local/share/whizard/models/SM.mdl'
| Preloaded model: SM
! Process library 'default_lib': initialized
! Preloaded library: default_lib
| Reading commands from file 'hello.sin'
Hello World!
| WHIZARD run finished.
|=============================================================================|

If this has just worked for you, you can be confident that you have a working WHIZARD installation, and you have been able to successfully run the program.

3.2  A Simple Calculation

You may object that WHIZARD is not exactly designed for printing out plain text. So let us demonstrate a more useful example.

Looking at the Hello World output, we first observe that the program writes a log file named (by default) whizard.log. This file receives all screen output, except for the output of external programs that are called by WHIZARD. You don’t have to cache WHIZARD’s screen output yourself.

After the welcome banner, WHIZARD tells you that it reads a physics model, and that it initializes and preloads a process library. The process library is initially empty. It is ready for receiving definitions of elementary high-energy physics processes (scattering or decay) that you provide. The processes are set in the context of a definite model of high-energy physics. By default this is the Standard Model, dubbed SM.

Here is the SINDARIN code for defining a SM physics process, computing its cross section, and generating a simulated event sample in Les Houches event format:

process ee = e1, E1 => e2, E2
sqrts = 360 GeV
n_events = 10
sample_format = lhef
simulate (ee)

As before, you save this text in a file (named, e.g., ee.sin) which is run by

/home/user$ whizard -r ee.sin

(We will come to the meaning of the -r option later.) This produces a lot of output which looks similar to this:

 | Writing log to 'whizard.log'
[... banner ...]
 |=============================================================================|
 |                               WHIZARD 2.4.1
 |=============================================================================|
 | Reading model file '/usr/local/share/whizard/models/SM.mdl'
 | Preloaded model: SM
 | Process library 'default_lib': initialized
 | Preloaded library: default_lib
 | Reading commands from file 'ee.sin'
 | Process library 'default_lib': recorded process 'ee'
 sqrts =  3.600000000000E+02
 n_events = 10
 
 | Starting simulation for process 'ee'
 | Simulate: process 'ee' needs integration
 | Integrate: current process library needs compilation
 | Process library 'default_lib': compiling ...
 | Process library 'default_lib': writing makefile
 | Process library 'default_lib': removing old files
 rm -f default_lib.la
 rm -f default_lib.lo default_lib_driver.mod opr_ee_i1.mod ee_i1.lo
 rm -f ee_i1.f90
 | Process library 'default_lib': writing driver
 | Process library 'default_lib': creating source code
 rm -f ee_i1.f90
 rm -f opr_ee_i1.mod
 rm -f ee_i1.lo
 /usr/local/bin/omega_SM.opt -o ee_i1.f90 -target:whizard
  -target:parameter_module parameters_SM -target:module opr_ee_i1 
  -target:md5sum '70DB728462039A6DC1564328E2F3C3A5' -fusion:progress 
  -scatter 'e- e+ -> mu- mu+' 
 [1/1] e- e+ -> mu- mu+ ... allowed. [time: 0.00 secs, total: 0.00 secs, remaining: 0.00 secs]
 all processes done. [total time: 0.00 secs]
 SUMMARY: 6 fusions, 2 propagators, 2 diagrams
 | Process library 'default_lib': compiling sources
[.....]
 
 | Process library 'default_lib': loading
 | Process library 'default_lib': ... success.
 | Integrate: compilation done
 | RNG: Initializing TAO random-number generator
 | RNG: Setting seed for random-number generator to 9616
 | Initializing integration for process ee:
 | ------------------------------------------------------------------------
 | Process [scattering]: 'ee'
 |   Library name  = 'default_lib'
 |   Process index = 1
 |   Process components:
 |     1: 'ee_i1':   e-, e+ => mu-, mu+ [omega]
 | ------------------------------------------------------------------------
 | Beam structure: [any particles]
 | Beam data (collision):
 |   e-  (mass = 5.1099700E-04 GeV)
 |   e+  (mass = 5.1099700E-04 GeV)
 |   sqrts = 3.600000000000E+02 GeV
 | Phase space: generating configuration ...
 | Phase space: ... success.
 | Phase space: writing configuration file 'ee_i1.phs'
 | Phase space: 2 channels, 2 dimensions
 | Phase space: found 2 channels, collected in 2 groves.
 | Phase space: Using 2 equivalences between channels.
 | Phase space: wood
 Warning: No cuts have been defined.
 
 | Starting integration for process 'ee'
 | Integrate: iterations not specified, using default
 | Integrate: iterations = 3:1000:"gw", 3:10000:""
 | Integrator: 2 chains, 2 channels, 2 dimensions
 | Integrator: Using VAMP channel equivalences
 | Integrator: 1000 initial calls, 20 bins, stratified = T
 | Integrator: VAMP
 |=============================================================================|
 | It      Calls  Integral[fb]  Error[fb]   Err[%]    Acc  Eff[%]   Chi2 N[It] |
 |=============================================================================|
    1        784  8.3282892E+02  1.68E+00    0.20    0.06*  39.99
    2        784  8.3118961E+02  1.23E+00    0.15    0.04*  76.34
    3        784  8.3278951E+02  1.36E+00    0.16    0.05   54.45
 |-----------------------------------------------------------------------------|
    3       2352  8.3211789E+02  8.01E-01    0.10    0.05   54.45    0.50   3
 |-----------------------------------------------------------------------------|
    4       9936  8.3331732E+02  1.22E-01    0.01    0.01*  54.51
    5       9936  8.3341072E+02  1.24E-01    0.01    0.01   54.52
    6       9936  8.3331151E+02  1.23E-01    0.01    0.01*  54.51
 |-----------------------------------------------------------------------------|
    6      29808  8.3334611E+02  7.10E-02    0.01    0.01   54.51    0.20   3
 |=============================================================================|
 
[.....]
| Simulate: integration done
| Simulate: using integration grids from file 'ee_m1.vg'
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 9617
| Simulation: requested number of events = 10
|             corr. to luminosity [fb-1] =   1.2000E-02
| Events: writing to LHEF file 'ee.lhe'
| Events: writing to raw file 'ee.evx'
| Events: generating 10 unweighted, unpolarized events ...
| Events: event normalization mode '1'
|         ... event sample complete.
| Events: closing LHEF file 'ee.lhe'
| Events: closing raw file 'ee.evx'
| There were no errors and    1 warning(s).
| WHIZARD run finished.
|=============================================================================|
 

The final result is the desired event file, ee.lhe.

Let us discuss the output quickly to walk you through the procedures of a WHIZARD run: after the logfile message and the banner, the reading of the physics model and the initialization of a process library, the recorded process with tag ’ee’ is recorded. Next, user-defined parameters like the center-of-mass energy and the number of demanded (unweighted) events are displayed. As a next step, WHIZARD is starting the simulation of the process with tag ’ee’. It recognizes that there has not yet been an integration over phase space (done by an optional integrate command, cf. Sec. 5.7.1), and consequently starts the integration. It then acknowledges, that the process code for the process ’ee’ needs to be compiled first (done by an optional compile command, cf. Sec. 5.4.5). So, WHIZARD compiles the process library, writes the makefile for its steering, and as a safeguard against garbage removes possibly existing files. Then, the source code for the library and its processes are generated: for the process code, the default method – the matrix element generator O’Mega is called (cf. Sec. 9.3); and the sources are being compiled.

The next steps are the loading of the process library, and WHIZARD reports the completion of the integration. For the Monte-Carlo integration, a random number generator is initialized. Here, it is the default generator, TAO (for more details, cf. Sec. 6.2, while the random seed is set to a value initialized by the system clock, as no seed has been provided in the SINDARIN input file.

Now, the integration for the process ’ee’ is initialized, and information about the process (its name, the name of its process library, its index inside the library, and the process components out of which it consists, cf. Sec. 5.4.4) are displayed. Then, the beam structure is shown, which in that case are symmetric partonic electron and positron beams with the center-of-mass energy provided by the user (360 GeV). The next step is the generation of the phase space, for which the default phase space method wood (for more details cf. Sec. 8.2) is selected. The integration is performed, and the result with absolute and relative error, unweighting efficiency, accuracy, χ2 quality is shown.

The final step is the event generation (cf. Chap. 11). The integration grids are now being used, again the random number generator is initialized. Finally, event generation of ten unweighted events starts (WHIZARD let us know to which integrated luminosity that would correspond), and events are written both in an internal (binary) event format as well as in the demanded LHE format. This concludes the WHIZARD run.

After a more comprehensive introduction into the SINDARIN steering language in the next chapter, Chap. 4, we will discuss all the details of the different steps of this introductory example.


Previous Up Next