whizard is hosted by Hepforge, IPPP Durham
Previous Up Next

Chapter 14  User Interfaces for WHIZARD

14.1  Command Line and SINDARIN Input Files

The standard way of using WHIZARD involves a command script written in SINDARIN. This script is executed by WHIZARD by mentioning it on the command line:

  whizard script-name.sin

You may specify several script files on the command line; they will be executed consecutively.

If there is no script file, WHIZARD will read commands from standard input. Hence, this is equivalent:

  cat script-name.sin | whizard

When executed from the command line, WHIZARD accepts several options. They are given in long form, i.e., they begin with two dashes. Values that belong to options follow the option string, separated either by whitespace or by an equals sign. Hence, --prefix /usr and --prefix=/usr are equivalent. Some options are also available in short form, a single dash with a single letter. Short-form options can be concatenated, i.e., a dash followed by several option letters.

The first set of options is intended for normal operation.

--debug AREA
: Switch on debug output for AREA. AREA can be one of WHIZARD’s source directories or all.
--debug2 AREA
: Switch on more verbose debug output for AREA.
: Only compute one phase-space point (for debugging).
--execute COMMANDS
: Execute COMMANDS as a script before the script file (see below). Short version: -e
--file CMDFILE
: Execute commands in CMDFILE before the main script file (see below). Short version: -f
: List the available options and exit. Short version: -h
: Run WHIZARD interactively. See Sec. 14.2. Short version: -i.
--library LIB
: Preload process library LIB (instead of the default processes). Short version: -l.
--localprefix DIR
: Search in DIR for local models. Default is $HOME/.whizard.
--logfile FILE
: Write log to FILE. Default is whizard.log. Short version: -L.
: Start logging on startup (default).
--model MODEL
: Preload model MODEL. Default is the Standard Model SM. Short version: -m.
: Do not display banner at startup.
: Do not preload a library.
: Do not write a logfile.
: Do not issue information into the logfile.
: Do not preload a specific physics model.
: Do not force a rebuild.
--query VARIABLE
: Display documentation of VARIABLE. Short version: -q.
: Do not preload a process library and do all calculations from scratch, even if results exist. This combines all rebuild options. Short version: -r.
: Rebuild the process library, even if code exists.
: Rebuild the phase space setup, even if it exists.
: Redo the integration, even if previous grids and results exist.
: Redo event generation, discarding previous event files.
: Show build-time configuration.
: Print version information and exit. Short version: -V.
: Any further options are interpreted as file names.

The second set of options refers to the configuration. They are relevant when dealing with a relocated WHIZARD installation, e.g., on a batch systems.

--prefix DIR
: Specify the actual location of the WHIZARD installation, including all subdirectories.
--exec-prefix DIR
: Specify the actual location of the machine-specific parts of the WHIZARD installation (rarely needed).
--bindir DIR
: Specify the actual location of the executables contained in the WHIZARD installation (rarely needed).
--libdir DIR
: Specify the actual location of the libraries contained in the WHIZARD installation (rarely needed).
--includedir DIR
: Specify the actual location of the include files contained in the WHIZARD installation (rarely needed).
--datarootdir DIR
: Specify the actual location of the data files contained in the WHIZARD installation (rarely needed).
: Specify the actual location and name of the libtool script that should be used by WHIZARD.
--lhapdfdir DIR
: Specify the actual location and of the LHAPDF installation that should be used by WHIZARD.

The --execute and --file options allow for fine-tuning the command flow. The WHIZARD main program will concatenate all commands given in --execute commands together with all commands contained in --file options, in the order they are encountered, as a contiguous command stream that is executed before the main script (in the example above, script-name.sin).

Regarding the --execute option, commands that contain blanks must be enclosed in matching single- or double-quote characters since the individual tokens would otherwise be intepreted as separate option strings. Unfortunately, a Unix/Linux shell interpreter will strip quotes before handing the command string over to the program. In that situation, the quote-characters must be quoted themselves, or the string must be enclosed in quotes twice. Either version should work as a command line interpreted by the shell:

  whizard --execute \'int my_flag = 1\' script-name.sin
  whizard --execute "'int my_flag = 1'" script-name.sin

14.2  WHISH – The WHIZARD Shell/Interactive mode

WHIZARD can be also run in the interactive mode using its own shell environment. This is called the WHIZARD Shell (WHISH). For this purpose, one starts with the command

  /home/user$ whizard --interactive


  /home/user$ whizard -i

WHIZARD will preload the Standard Model and display a command prompt:


You now can enter one or more SINDARIN commands, just as if they were contained in a script file. The commands are compiled and executed after you hit the ENTER key. When done, you get a new prompt. The WHISH can be closed by the quit command:

  whish? quit

Obviously, each input must be self-contained: commands must be complete, and conditionals or scans must be closed on the same line.

If WHIZARD is run without options and without a script file, it also reads commands interactively, from standard input. The difference is that in this case, interactive input is multi-line, terminated by Ctrl-D, the script is then compiled and executed as a whole, and WHIZARD terminates.

In WHISH mode, each input line is compiled and executed individually. Furthermore, fatal errors are masked, so in case of error the program does not terminate but returns to the WHISH command line. (The attempt to recover may fail in some circumstances, however.)

14.3  Graphical user interface

This is still experimental.

WHIZARD ships with a graphical interface that can be steered in a browser of your choice. It is located in share/gui. To use it, you have to run npm install (which will install javascript libraries locally in that folder) and npm start (which will start a local web server on your machine) in that folder. More technical details and how to get npm is discussed in share/gui/README.md. When it is running, you can access the GUI by entering localhost:3000 as address in your browser. The GUI is separated into different tabs for basic settings, integration, simulation, cuts, scans, NLO and beams. You can select and enter what you are interested in and the GUI will produce a SINDARIN file. You can use the GUI to run WHIZARD with that SINDARIN or just produce it with the GUI and then tweak it further with an editor. In case you run it in the GUI, the log file will be updated in the browser as it is produced. Any SINDARIN features that are not supported by the GUI can be added directly as "Additional Code".

14.4  WHIZARD as a library

This is planned, but not implemented yet.

Previous Up Next