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.
--single-event
: 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
--help
: List the available options and exit. Short version: -h
--interactive
: 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.
--logging
: Start logging on startup (default).
--model MODEL
: Preload model MODEL. Default is the Standard Model SM. Short version: -m.
--no-banner
: Do not display banner at startup.
--no-library
: Do not preload a library.
--no-logfile
: Do not write a logfile.
--no-logging
: Do not issue information into the logfile.
--no-model
: Do not preload a specific physics model.
--no-rebuild
: Do not force a rebuild.
--query VARIABLE
: Display documentation of VARIABLE. Short version: -q.
--rebuild
: 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-library
: Rebuild the process library, even if code exists.
--rebuild-phase-space
: Rebuild the phase space setup, even if it exists.
--rebuild-grids
: Redo the integration, even if previous grids and results exist.
--rebuild-events
: Redo event generation, discarding previous event files.
--show-config
: Show build-time configuration.
--version
: 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).
--libtool LOCAL_LIBTOOL
: 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

or

  /home/user$ whizard -i

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

  whish?

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

The compiled WHIZARD program consists of two libraries (libwhizard and libomega). In the standard setup, these are linked to a short main program which deals with command line options and top-level administration. This is the stand-alone whizard executable program.

Alternatively, it is possible to link the libraries to a different main program of the user’s choice. The user program can take complete control of the WHIZARD features. The libwhizard library provides an API, a well-defined set of procedures which can be called from a foreign main program. The supported languages are Fortran, C, and C++. Using the C API, any other language which supports linking against C libraries can also be interfaced.

14.4.1 Fortran main program

To link a Fortran main program with the WHIZARD library, the following steps must be performed:

  1. Configure, build and install WHIZARD as normal.
  2. Include code for accessing WHIZARD functionality in the user program. The code should initialize WHIZARD, execute the intended commands, and finalize. For an example, see below.
  3. Compile the user program. The user program must be compiled with the same Fortran compiler that has been used for the WHIZARD build.

    If necessary, specify an option that finds the installed WHIZARD module files. For instance, if WHIZARD has been installed in whizard-path, this should read

        -Iwhizard-path/lib/mod/whizard
      
  4. Link the program (or compile-link in a single step). If necessary, specify options that find the installed WHIZARD and O’Mega libraries. For instance, if WHIZARD has been installed in whizard-path, this should read
        -Lwhizard-path/lib -lwhizard -lwhizard_prebuilt -lomega
      
    On some systems, you may have to replace lib by lib64.

    Such an example compile-link could look like

        gfortran manual_example_api.f90 -Lwhizard-path/lib -lwhizard -lwhizard_prebuilt -lomega
      

    If WHIZARD has been compiled with a non-default Fortran compiler, you may have to explicitly link the appropriate Fortran run-time libraries.

    The tirpc library is used by the StdHEP subsystem for xdr functionality. This library should be present on the host system. This library needs only be linked of the SunRPC library is not installed on the system.

    If additional libraries such as HepMC are enabled in the WHIZARD configuration, it may be necessary to provide extra options for linking those.

    An example here looks like

        gfortran manual_example_api.f90 -Lwhizard-path/lib -lwhizard
            -lwhizard_prebuilt -lomega -lHepMC3 -lHepMC3rootIO -llcio
      
  5. Run the program. If necessary, provide the path to the installed shared libraries. For instance, if WHIZARD has been installed in whizard-path, this should read
        export LD_LIBRARY_PATH="whizard-path/lib:$LD_LIBRARY_PATH"
      
    On some systems, you may have to replace lib by lib64, as above.

    The WHIZARD subsystem will work with input and output files in the current working directory, unless asked to do otherwise.

Below is an example program, adapted from WHIZARD’s internal unit-test suite. The user program controls the WHIZARD workflow in the same way as a SINDARIN script would do. The commands are a mixture of SINDARIN command calls and functionality for passing information between the WHIZARD subsystem and the host program. In particular, the program can process generated events one-by-one.

program main

  ! WHIZARD API as a module
  use api

  ! Standard numeric types
  use iso_fortran_env, only: real64, int32

  implicit none

  ! WHIZARD and event-sample objects
  type(whizard_api_t)    :: whizard
  type(simulation_api_t) :: sample

  ! Local variables
  real(real64)   :: integral, error
  real(real64)   :: sqme, weight
  integer(int32) :: idx
  integer(int32) :: i, it_begin, it_end

  ! Initialize WHIZARD, setting some global option
  call whizard%option ("model", "QED")
  call whizard%init ()

  ! Define a process, set some variables
  call whizard%command ("process mupair = e1, E1 => e2, E2")
  call whizard%set_var ("sqrts", 100._real64)
  call whizard%set_var ("seed", 0)

  ! Generate matrix-element code, integrate and retrieve result
  call whizard%command ("integrate (mupair)")
  call whizard%get_integration_result ("mupair", integral, error)

  ! Print result
  print 1, "cross section =", integral / 1000, "pb"
  print 1, "error         =", error    / 1000, "pb"
1 format (2x,A,1x,F5.1,1x,A)
2 format (2x,A,1x,L1)

  ! Settings for event generation
  call whizard%set_var ("$sample", "mupair_events")
  call whizard%set_var ("n_events", 2)

  ! Create an event-sample object and generate events
  call whizard%new_sample ("mupair", sample)
  call sample%open (it_begin, it_end)
  do i = it_begin, it_end
     call sample%next_event ()
     call sample%get_event_index (idx)
     call sample%get_weight (weight)
     call sample%get_sqme (sqme)
     print "(A,I0)", "Event #", idx
     print 3, "sqme    =", sqme
     print 3, "weight  =", weight
3    format (2x,A,1x,ES10.3)
  end do

  ! Finalize the event-sample object
  call sample%close ()

  ! Finalize the WHIZARD object
  call whizard%final ()

end program main

The API provides the following commands as Fortran subroutines. Most of them are used in the example above.

Module

There is only one module from the WHIZARD package which must be used by the user program:

use api

You may use any other WHIZARD module in our program, all module files are part of the installation. Be aware, however, that all other modules are considered internal. Unless explictly mentioned in this manual, interfaces are not documented here and may change between versions.

Changes to the api module, if any, will be documented here.

Master object

All functionality is accessed via a master API object which should be declared as follows:

type(whizard_api_t) :: whizard

There should be only one master object.

Pre-Initialization options

Before initializing the API object, it is possible to provide options. The available options mirror the command-line options of the stand-alone program, cf. Sec. ‍14.1.

call whizard%option (key, value)

All keys and values are Fortran character strings. The following options are available. For all options, default values exist as listed in Sec. ‍14.1.

model
Model that should be preloaded.
library
Name of the library where matrix-element code should end up.
logfile
Name of the logfile that WHIZARD will write.
job_id
Name of the current job; can be used for writing unique output files.
unpack
Comma-separated list of files to be uncompressed and unpacked (via tar and gzip) when init is called on the API object.
pack
Comma-separated list of files or directories to be packed and compressed when final is called.
rebuild
All of the following:
rebuild_library
Force rebuilding a matrix-element code library, overwriting results from a previous run.
recompile
Force recompiling the matrix-element code library.
rebuild_grids
Force reproducing integration passes.
rebuild_events
Force regenerating event samples.

Initialization and finalization

After options have been set, the system is initialized via

call whizard%init

Once initialized, WHIZARD can execute commands as listed below. When this is complete, clean up by

call whizard%final

Variables and values

In the API, WHIZARD requires numeric data types according to the IEEE standard, which is available to Fortran in the iso_fortran_env intrinsic module. Strictly speaking, integer data must have type int32, and real data must have type real64.

For most systems and default compiler settings, it is not really necessary to use the ISO module and its data types. Integers map to default Fortran integer, and real values map to default Fortran double precision.

As an alternative, you may use the WHIZARD internal kinds module which declares a real(default) type

use kinds, only: default

On most systems, this will be equivalent to real(real64).

To set a SINDARIN variable, use the function that corresponds to the data type:

call whizard%set_var (name, value)

The name is a Fortran string which has to be equal to the name of the corresponding SINDARIN variable, including any prefix character ($ or ?). The value depends on the type of the SINDARIN variable.

To retrieve the current value of a variable:

call whizard%get_var (name, var)

The variable must be declared as integer, real(real64), logical, or character(:), allocatable. This depends on the SINDARIN variable type.

Commands

Any SINDARIN command can be called via

call whizard%command (command)

command is a Fortran character string, as it would appear in a SINDARIN script.

This includes, in particular, the important commands process, integrate, and simulate. You may also set variables that way.

Retrieving cross-section results

This call returns the results (integration and error) from a preceding integration run for the process process-name:

call whizard%get_integration_result ("process-name", integral, error)

There is also an optional argument known of type logical which is set if the integration run was successful, so integral and error are meaningful.

Event-sample object

A simulate command will produce an event sample. With the appropriate settings, the sample will be written to file in any chosen format, to be post-processed when it is complete.

However, a possible purpose of using the WHIZARD API is to process events one-by-one when they are generated. To this end, there is an event-sample handle, which can be declared in this way:

type(simulation_api_t) :: sample

An instance sample of this type is created by this factory method:

call whizard%new_sample ("process-name(s)", sample)

The command accepts a comma-separated list of process names which should be included in the event sample.

To start event generation for this sample, call

call sample%open (it_begin, it_end )

where the two output parameters (integers) it_begin and it_end provide the bounds for an event loop in the calling program. (In serial mode, the bounds are equal to 1 and n_events, respectively, but in an MPI parallel environment, they depend on the computing node.)

This command generates a new event, to be enclosed within an event loop:

call sample%next_event

The event will be available by format-specific access methods, see below.

This command closes and deletes an event sample after the event loop has completed:

call sample%close

Retrieving event data

After a call to next_event, the sample object can be queried for specific event data.

call sample%get_event_index (value)

returns the index (integer counter) of the current event.

call sample%get_process_index (value)
call sample%get_process_id (
value)

returns the numeric (string) ID of the hard process, respectively, that was generated in this event. The variables must be declared as integer and character(:), allocatable, respectively.

The following methods return real(real64) values.

call sample%get_sqrts (value)

returns the √s value of this event.

call sample%get_fac_scale (value)

returns the factorization scale of this event (value).

call sample%get_alpha_s (value)

returns the value of the strong coupling for this event (value).

call sample%get_sqme (value)

returns the value of the squared matrix element (summed over final states and averaged over initial states).

call sample%get_weight (value)

returns the Monte-Carlo weight of this event.

Access to the event record depends on the event format that has been selected. The format must allow access to individual events via data structures in memory. There are three cases where such structures exist and are accessible:

  1. If the event format uses a COMMON block, event data is accessible via this COMMON block, which must be declared in the calling routine.
  2. The HepMC event format communicates via a C++ object. In Fortran, there is a wrapper which has to be declared as
    type(hepmc_event_t) :: hepmc_event
    To activate this handle, the next_event call must reference it as an argument:
    call sample%next_event (hepmc_event)
    The WHIZARD module hepmc_interface contains procedures which can work with this record. A pointer to the actual C++ object can be retrieved as a Fortran c_ptr object as follows:
    type(c_ptr) :: hepmc_ptr

    hepmc_ptr = hepmc_event_get_c_ptr (hepmc_event)
  3. The LCIO event format also communicates via a C++ object. The access methods are entirely analogous, replacing hepmc by lcio in all calls and names.

14.4.2 C main program

To link a C main program with the WHIZARD library, the following steps must be performed:

  1. Configure, build and install WHIZARD as normal.
  2. Include code for accessing WHIZARD functionality in the user program. The code should initialize WHIZARD, execute the intended commands, and finalize. For an example, see below.
  3. Compile the user program with the option that finds the WHIZARD C/C++ interface header file. For instance, if WHIZARD has been installed in whizard-path, this should read
        -Iwhizard-path/include
      
  4. Link the program with the necessary libraries (or compile-link in a single step). If WHIZARD has been installed in a system path, this should work automatically. If WHIZARD has been installed in a non-default whizard-path, these are the options:
        -Lwhizard-path/lib -lwhizard -lwhizard_prebuilt -lomega -ltirpc
      
    On some systems, you may have to replace lib by lib64.

    If WHIZARD has been compiled with a non-default Fortran compiler, you may have to explicitly link the appropriate Fortran run-time libraries.

    The tirpc library is used by the StdHEP subsystem for xdr functionality. This library should be present on the host system. Cf. the corresponding remarks in the section for a Fortran main program.

    If additional libraries such as HepMC are enabled in the WHIZARD configuration, it may be necessary to provide extra options for linking those.

  5. Run the program. If necessary, provide the path to the installed shared libraries. For instance, if WHIZARD has been installed in whizard-path, this should read
        export LD_LIBRARY_PATH="whizard-path/lib:$LD_LIBRARY_PATH"
      
    On some systems, you may have to replace lib by lib64, as above.

    The WHIZARD subsystem will work with input and output files in the current working directory, unless asked to do otherwise.

Below is an example program, adapted from WHIZARD’s internal unit-test suite. The user program controls the WHIZARD workflow in the same way as a SINDARIN script would do. The commands are a mixture of SINDARIN command calls and functionality for passing information between the WHIZARD subsystem and the host program. In particular, the program can process generated events one-by-one.

#include <stdio.h>
#include "whizard.h"

int main( int argc, char* argv[] )
{
  /* WHIZARD and event-sample objects */
  void* wh;
  void* sample;

  /* Local variables */
  double integral, error;
  double sqme, weight;
  int idx;
  int it, it_begin, it_end;

  /* Initialize WHIZARD, setting some global option */
  whizard_create( &wh );
  whizard_option( &wh, "model", "QED" );
  whizard_init( &wh );

  /* Define a process, set some variables */
  whizard_command( &wh, "process mupair = e1, E1 => e2, E2" );
  whizard_set_double( &wh, "sqrts", 10. );
  whizard_set_int( &wh, "seed", 0 );

  /* Generate matrix-element code, integrate and retrieve result */
  whizard_command( &wh, "integrate (mupair)" );

  /* Print result */
  whizard_get_integration_result( &wh, "mupair", &integral, &error);
  printf( "  cross section = %5.1f pb\n", integral / 1000. );
  printf( "  error         = %5.1f pb\n", error / 1000. );

  /* Settings for event generation */
  whizard_set_char( &wh, "$sample", "mupair_events" );
  whizard_set_int( &wh, "n_events", 2 );

  /* Create an event-sample object and generate events */
  whizard_new_sample( &wh, "mupair", &sample );
  whizard_sample_open( &sample, &it_begin, &it_end );
  for (it=it_begin; it<=it_end; it++) {
    whizard_sample_next_event( &sample );
    whizard_sample_get_event_index( &sample, &idx );
    whizard_sample_get_weight( &sample, &weight );
    whizard_sample_get_sqme( &sample, &sqme );
    printf( "Event #%d\n", idx );
    printf( "  sqme    = %10.3e\n", sqme );
    printf( "  weight  = %10.3e\n", weight );
  }

  /* Finalize the event-sample object */
  whizard_sample_close( &sample );

  /* Finalize the WHIZARD object */
  whizard_final( &wh );
}

Header

The necessary declarations are imported by the directive

#include "whizard.h"

Master object

All functionality is accessed via a master API object which should be declared as a void* pointer:

void* wh;

The object must be explicitly created:

whizard_create( &wh );

There should be only one master object.

Pre-Initialization options

Before initializing the API object, it is possible to provide options. The available options mirror the command-line options of the stand-alone program, cf. Sec. ‍14.1.

whizard_option( &wh, key, value );

All keys and values are null-terminated C character strings. The available options are listed above in the Fortran interface documentation.

Initialization and finalization

After options have been set, the system is initialized via

whizard_init( &wh );

Once initialized, WHIZARD can execute commands as listed below. When this is complete, clean up by

whizard_final( &wh );

Variables and values

In the API, WHIZARD requires numeric data types according to the IEEE standard. Integers map to C int, and real values map to C double. Logical values map to C int interpreted as bool, and string values map to null-terminated C strings.

To set a SINDARIN variable of appropriate type:

whizard_set_int ( &wh, name, value );
whizard_set_double ( &wh,
name, value );
whizard_set_bool ( &wh,
name, value );
whizard_set_char ( &wh,
name, value );

name is declared const char*. It must match the corresponding SINDARIN variable name, including any prefix character ($ or ?). value is declared const double/int/char*.

To retrieve the current value of a variable:

whizard_get_int ( &wh, name, &var );
whizard_get_double ( &wh,
name, &var );
whizard_get_bool ( &wh,
name, &var );
whizard_get_char ( &wh,
name, var, len );

Here, var is a C variable of appropriate type. In the character case, var is a C character array declared as var[len]. The functions return zero if the SINDARIN variable has a known value.

Commands

Any SINDARIN command can be called via

whizard_command( &wh, command );

command is a null-terminated C string that contains commands as they would appear in a SINDARIN script.

This includes, in particular, the important commands process, integrate, and simulate. You may also set variables that way.

Retrieving cross-section results

This call returns the results (integration and error) from a preceding integration run for the process process-name:

whizard_get_integration_result( &wh, "process-name", &integral, &error)

integral and error are C variables of type double. The function returns zero if the integration run was successful, so integral and error are meaningful.

Event-sample object

A simulate command will produce an event sample. With the appropriate settings, the sample will be written to file in any chosen format, to be post-processed when it is complete.

However, a possible purpose of using the WHIZARD API is to process events one-by-one when they are generated. To this end, there is an event-sample handle, which can be declared in this way:

void* sample;

An instance sample of this type is created by this factory method:

whizard_new_sample( &wh, "process-name(s)", &sample);

The command accepts a comma-separated list of process names which should be included in the event sample.

To start event generation for this sample, call

whizard_sample_open( &sample, &it_begin, &it_end );

where the two output variables (int) it_begin and it_end provide the bounds for an event loop in the calling program. (In serial mode, the bounds are equal to 1 and n_events, respectively, but in an MPI parallel environment, they depend on the computing node.)

This command generates a new event, to be enclosed within an event loop:

whizard_sample_next_event( &sample );

The event will be available by format-specific access methods, see below.

This command closes and deletes an event sample after the event loop has completed:

whizard_sample_close( &sample );

Retrieving event data

After a call to whizard_sample_next_event, the sample object can be queried for specific event data.

whizard_sample_get_event_index( &sample, &value );
whizard_sample_get_process_index( &
sample, &value );
whizard_sample_get_process_id( &
sample, value, len );
whizard_sample_get_sqrts( &
sample, &value );
whizard_sample_get_fac_scale( &
sample, &value );
whizard_sample_get_alpha_s( &
sample, &value );
whizard_sample_get_sqme( &
sample, &value );
whizard_sample_get_weight( &
sample, &value );

where the value is a variable of appropriate type (see above).

Event data are stored in a format-specific way. This may be a COMMON block, or a HepMC or LCIO event record. In the latter cases, cf. the C++ API below for access information.

14.4.3 C++ main program

To link a C++ main program with the WHIZARD library, the following steps must be performed:

  1. Configure, build and install WHIZARD as normal.
  2. Include code for accessing WHIZARD functionality in the user program. The code should initialize WHIZARD, execute the intended commands, and finalize. For an example, see below.
  3. Compile the user program with the option that finds the WHIZARD C/C++ interface header file. For instance, if WHIZARD has been installed in whizard-path, this should read
        -Iwhizard-path/include
      
  4. Link the program with the necessary libraries (or compile-link in a single step). If WHIZARD has been installed in a system path, this should work automatically. If WHIZARD has been installed in a non-default whizard-path, these are the options:
        -Lwhizard-path/lib -lwhizard -lwhizard_prebuilt -lomega -ltirpc
      
    On some systems, you may have to replace lib by lib64.

    If WHIZARD has been compiled with a non-default Fortran compiler, you may have to explicitly link the appropriate Fortran run-time libraries.

    The tirpc library is used by the StdHEP subsystem for xdr functionality. This library should be present on the host system.

    If additional libraries such as HepMC are enabled in the WHIZARD configuration, it may be necessary to provide extra options for linking those.

  5. Run the program. If necessary, provide the path to the installed shared libraries. For instance, if WHIZARD has been installed in whizard-path, this should read
        export LD_LIBRARY_PATH="whizard-path/lib:$LD_LIBRARY_PATH"
      
    On some systems, you may have to replace lib by lib64, as above.

    The WHIZARD subsystem will work with input and output files in the current working directory, unless asked to do otherwise.

Below is an example program, adapted from WHIZARD’s internal unit-test suite. The user program controls the WHIZARD workflow in the same way as a SINDARIN script would do. The commands are a mixture of SINDARIN command calls and functionality for passing information between the WHIZARD subsystem and the host program. In particular, the program can process generated events one-by-one.

#include <cstdio>
#include <string>
#include "whizard.h"

int main( int argc, char* argv[] )
{
  // WHIZARD and event-sample objects
  Whizard* whizard;
  WhizardSample* sample;

  // Local variables
  double integral, error;
  double sqme, weight;
  int idx;
  int it, it_begin, it_end;

  // Initialize WHIZARD, setting some global option
  whizard = new Whizard();
  whizard->option( "model", "QED" );
  whizard->init();

  // Define a process, set some variables
  whizard->command( "process mupair = e1, E1 => e2, E2" );
  whizard->set_double( "sqrts", 10. );
  whizard->set_int( "seed", 0 );

  // Generate matrix-element code, integrate and retrieve result
  whizard->command( "integrate (mupair)" );

  // Print result
  whizard->get_integration_result( "mupair", &integral, &error );
  printf( "  cross section = %5.1f pb\n", integral / 1000. );
  printf( "  error         = %5.1f pb\n", error / 1000. );

  // Settings for event generation
  whizard->set_string( "$sample", "mupair_events" );
  whizard->set_int( "n_events", 2 );

  // Create an event-sample object and generate events
  sample = whizard->new_sample( "mupair" );
  sample->open( &it_begin, &it_end );
  for (it=it_begin; it<=it_end; it++) {
    sample->next_event();
    idx = sample->get_event_index();
    weight = sample->get_weight();
    sqme = sample->get_sqme();
    printf( "Event #%d\n", idx );
    printf( "  sqme    = %10.3e\n", sqme );
    printf( "  weight  = %10.3e\n", weight );
  }

  // Finalize the event-sample object
  sample->close();
  delete sample;

  // Finalize the WHIZARD object
  delete whizard;
}

Header

The necessary declarations are imported by the directive

#include "whizard.h"

Master object

All functionality is accessed via a master API object which should be declared as follows:

Whizard* whizard;

The constructor takes no arguments:

whizard = new Whizard();

There should be only one master object.

Pre-Initialization options

Before initializing the API object, it is possible to provide options. The available options mirror the command-line options of the stand-alone program, cf. Sec. ‍14.1.

whizard->option( key, value );

All keys and values are C++ strings. The available options are listed above in the Fortran interface documentation.

Initialization and finalization

After options have been set, the system is initialized via

whizard->init();

Once initialized, WHIZARD can execute commands as listed below. When all is complete, delete the WHIZARD object. This will call the destructor that correctly finalizes the WHIZARD workflow.

Variables and values

In the API, WHIZARD requires numeric data types according to the IEEE standard. Integers map to C int, and real values map to C double. Logical values map to C int interpreted as bool, and string values map to C++ string.

To set a SINDARIN variable of appropriate type:

whizard->set_int ( name, value );
whizard->set_double (
name, value );
whizard->set_bool (
name, value );
whizard->set_string (
name, value );

name is a C++ string value. It must match the corresponding SINDARIN variable name, including any prefix character ($ or ?). value is a double/int/string, respectively.

To retrieve the current value of a variable:

whizard->get_int ( name, &var );
whizard->get_double (
name, &var );
whizard->get_bool (
name, &var );
whizard->get_string (
name, &var );

Here, var is a C variable of appropriate type. The functions return zero if the SINDARIN variable has a known value.

Commands

Any SINDARIN command can be called via

whizard->command( command );

command is a C++ string value that contains commands as they would appear in a SINDARIN script.

This includes, in particular, the important commands process, integrate, and simulate. You may also set variables that way.

Retrieving cross-section results

This call returns the results (integration and error) from a preceding integration run for the process process-name:

whizard->get_integration_result( "process-name", &integral, &error );

integral and error are variables of type double. The function returns zero if the integration run was successful, so integral and error are meaningful.

Event-sample object

A simulate command will produce an event sample. With the appropriate settings, the sample will be written to file in any chosen format, to be post-processed when it is complete.

However, a possible purpose of using the WHIZARD API is to process events one-by-one when they are generated. To this end, there is an event-sample handle, which can be declared in this way:

WhizardSample* sample;

An instance sample of this type is created by this factory method:

sample = whizard->new_sample( "process-name(s)" );

The command accepts a comma-separated list of process names which should be included in the event sample.

To start event generation for this sample, call

sample->open( &it_begin, &it_end);

where the two output variables (int) it_begin and it_end provide the bounds for an event loop in the calling program. (In serial mode, the bounds are equal to 1 and n_events, respectively, but in an MPI parallel environment, they depend on the computing node.)

This command generates a new event, to be enclosed within an event loop:

sample->next_event();

The event will be available by format-specific access methods, see below.

This command closes and deletes an event sample after the event loop has completed:

sample->close();

Retrieving event data

After a call to sample->next_event, the sample object can be queried for specific event data.

value = sample->get_event_index();
value = sample->get_process_index();
value = sample->get_process_id();
value = sample->get_sqrts();
value = sample->get_fac_scale();
value = sample->get_alpha_s();
value = sample->get_sqme();
value = sample->get_weight();

where the value is a variable of appropriate type (see above).

Event data are stored in a format-specific way. This may be a HepMC or LCIO C++ event record.

For interfacing with the HepMC event record, the appropriate declarations must be in place, e.g.,

#include "HepMC/GenEvent.h"
using namespace HepMC;

An event-record object must be declared,

GenEvent* evt;

and the WHIZARD event call must take the event as an argument

sample->next_event ( &evt );

This will create a new evt object. Then, the HepMC event record can be accessed via its own methods. After an event has been processed, the event record should be deleted

delete evt;

Analogously, for interfacing with the LCIO event record, the appropriate declarations must be in place, e.g.,

#include "lcio.h"
#include "IMPL/LCEventImpl.h"
using namespace lcio;

An event-record object must be declared,

LCEvent* evt;

and the WHIZARD event call must take the event as an argument

sample->next_event ( &evt );

This will create a new evt object. Then, the LCIO event record can be accessed via its own methods. After an event has been processed, the event record should be deleted

delete evt;

14.4.4 Python main program

To create a Python executable, WHIZARD provides a Cython interface that uses C++ bindings to link a dynamic library which can then be loaded as a module via Python. Note that WHIZARD’s Cython/Python interface only works with Pythonv3. Also make sure that you do not mix different Python versions when linking external programs which also provide Python interfaces like HepMC or LCIO.

To link a Python main program with the WHIZARD library, the following steps must be performed:

  1. Configure, build and install WHIZARD as normal.
  2. Include code for accessing WHIZARD functionality in the user program. The code should initialize WHIZARD, execute the intended commands, and finalize. For an example, see below.
  3. Run Python on the user program. Make sure that the operating system finds the WHIZARD Python and library path. If WHIZARD has been installed in a non-default whizard-path, these are the options:
        export PYTHONPATH=whizard-path/lib/python/site-packages/:$PYTHONPATH
      

    If necessary, provide the path to the installed shared libraries. For instance, if WHIZARD has been installed in whizard-path, this should read

        export LD_LIBRARY_PATH="whizard-path/lib:$LD_LIBRARY_PATH"
      

    On some systems, you may have to replace lib by lib64, as above.

    The WHIZARD subsystem will work with input and output files in the current working directory, unless asked to do otherwise.

  4. The tirpc library is used by the StdHEP subsystem for xdr functionality. This library should be present on the host system.
  5. Run the program.

Below is an example program, similar to WHIZARD’s internal unit-test suite for different external programming languages. The user program controls the WHIZARD workflow in the same way as a SINDARIN script would do. The commands are a mixture of SINDARIN command calls and functionality for passing information between the WHIZARD subsystem and the host program. In particular, the program can process generated events one-by-one.

import whizard

wz = whizard.Whizard()

wz.option("logfile", "whizard_1_py.log")
wz.option("job_id", "whizard_1_py_ID")
wz.option("library", "whizard_1_py_1_lib")
wz.option("model", "QED")

wz.init()

wz.set_double("sqrts", 100)
wz.set_int("n_events", 3)
wz.set_bool("?unweighted", True)
wz.set_string("$sample", "foobar")

wz.set_int("seed", 0)

wz.command("process whizard_1_py_1_p = e1, E1 => e2, E2")
wz.command("iterations = 1:100")

integral, error = wz.get_integration_result("whizard_1_py_1_p")
print(integral, error)

wz.command("integrate (whizard_1_py_1_p)")
sqrts = wz.get_double("sqrts")
print(f"sqrts  = {sqrts:5.1f} GeV")
print(f"sigma   = integral:5.1f} pb")
print(f"error    {error:5.1f} pb")

sample = wz.new_sample("whizard_1_py_p1, whizard_1_py_p2, whizard_1_py_p3")
it_begin, it_end = sample.open()
for it in range(it_begin, it_end + 1):
    sample.next_event()
    idx = sample.get_event_index()
    i_proc  = sample.get_process_index()
    proc_id = sample.get_process_id()
    f_scale = sample.get_fac_scale()
    alpha_s = sample.get_alpha_s()
    weight  = sample.get_weight()
    sqme    = sample.get_sqme()
    print(f"Event #{idx}")
    print(f"  process #{i_proc}")
    print(f"  proc_id = {proc_id}")
    print(f"  f_scale = {f_scale:10.3e}")
    print(f"  alpha_s = {f_scale:10.3e}")
    print(f"  sqme    = {f_scale:10.3e}")
    print(f"  weight  = {f_scale:10.3e}")

sample.close()

del(wz)

Python module import

There are no necessary headers here as all of this information has been automatically taken care by the Cython interface layer. The WHIZARD module needs to be imported by Python

import whizard

Master object

All functionality is accessed via a master API object which should be declared as follows:

wz = whizard.Whizard()

The constructor takes no arguments.There should be only one master object.

Pre-Initialization options

Before initializing the API object, it is possible to provide options. The available options mirror the command-line options of the stand-alone program, cf. Sec. ‍14.1.

wz.option( key, value );

All keys and values are Python strings. The available options are listed above in the Fortran interface documentation.

Initialization and finalization

After options have been set, the system is initialized via

wz.init()

Once initialized, WHIZARD can execute commands as listed below. When all is complete, delete the WHIZARD object. This will call the destructor that correctly finalizes the WHIZARD workflow.

Variables and values

In the API, WHIZARD requires numeric data types according to the IEEE standard. Integers map to Python int, and real values map to Python double. Logical values map to True and False, and string values map to Python strings.

To set a SINDARIN variable of appropriate type:

wz.set_int ( name, value );
wz.set_double (
name, value );
wz.set_bool (
name, value );
wz.set_string (
name, value );

name is a Python string value. It must match the corresponding SINDARIN variable name, including any prefix character ($ or ?). value is a double/int/string, respectively.

To retrieve the current value of a variable:

wz.get_int ( name, var );
wz.get_double (
name, var );
wz.get_bool (
name, var );
wz.get_string (
name, var );

Here, var is a Python variable of appropriate type. The functions return zero if the SINDARIN variable has a known value.

Commands

Any SINDARIN command can be called via

wz.command( command );

command is a Python string value that contains commands as they would appear in a SINDARIN script.

This includes, in particular, the important commands process, integrate, and simulate. You may also set variables that way.

Retrieving cross-section results

This call returns the results (integration and error) from a preceding integration run for the process process-name:

wz.get_integration_result( "process-name", integral, error );

integral and error are variables of type double. The function returns zero if the integration run was successful, so integral and error are meaningful.

Event-sample object

A simulate command will produce an event sample. With the appropriate settings, the sample will be written to file in any chosen format, to be post-processed when it is complete.

However, a possible purpose of using the WHIZARD API is to process events one-by-one when they are generated. To this end, there is an event-sample handle, which can be declared in this way:

WhizardSample* sample;

An instance sample of this type is created by this factory method:

sample = wz.new_sample( "process-name(s)" );

The command accepts a comma-separated list of process names which should be included in the event sample.

To start event generation for this sample, call

it_begin, it_end = wz.sample_open()

where the two output variables (int) it_begin and it_end provide the bounds for an event loop in the calling program. (In serial mode, the bounds are equal to 1 and n_events, respectively, but in an MPI parallel environment, they depend on the computing node.)

This command generates a new event, to be enclosed within an event loop:

sample.next_event();

The event will be available by format-specific access methods, see below.

This command closes and deletes an event sample after the event loop has completed:

sample.close();

Retrieving event data

After a call to sample.next_event, the sample object can be queried for specific event data.

value = sample.get_event_index();
value = sample.get_process_index();
value = sample.get_process_id();
value = sample.get_sqrts();
value = sample.get_fac_scale();
value = sample.get_alpha_s();
value = sample.get_sqme();
value = sample.get_weight();

where the value is a variable of appropriate type (see above).

Event data are stored in a format-specific way. This may be a HepMC or LCIO C++ event record, or some formats supported by WHIZARD intrinsically like LHEF etc.


Previous Up Next