Chapter 14 User Interfaces for WHIZARD
14.1 Command Line and SINDARIN Input FilesThe 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.
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.
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 modeWHIZARD 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 interfaceThis 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 libraryThe 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 programTo link a Fortran main program with the WHIZARD library, the following steps must be performed:
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.
The API provides the following commands as Fortran subroutines. Most of them are used in the example above. ModuleThere 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 objectAll 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 optionsBefore 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.
Initialization and finalizationAfter 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 valuesIn 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. CommandsAny 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 resultsThis 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 objectA 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 dataAfter 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) 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:
14.4.2 C main programTo link a C main program with the WHIZARD library, the following steps must be performed:
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.
HeaderThe necessary declarations are imported by the directive #include "whizard.h" Master objectAll 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 optionsBefore 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 finalizationAfter 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 valuesIn 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 ); 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 ); 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. CommandsAny 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 resultsThis 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 objectA 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 dataAfter a call to whizard_sample_next_event, the sample object can be queried for specific event data. whizard_sample_get_event_index( &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 programTo link a C++ main program with the WHIZARD library, the following steps must be performed:
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.
HeaderThe necessary declarations are imported by the directive #include "whizard.h" Master objectAll 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 optionsBefore 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 finalizationAfter 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 valuesIn 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 ); 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 ); Here, var is a C variable of appropriate type. The functions return zero if the SINDARIN variable has a known value. CommandsAny 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 resultsThis 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 objectA 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 dataAfter a call to sample->next_event, the sample object can be queried for specific event data. value = sample->get_event_index(); 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" 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" 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 programTo 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:
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.
Python module importThere 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 objectAll 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 optionsBefore 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 finalizationAfter 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 valuesIn 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 ); 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 ); Here, var is a Python variable of appropriate type. The functions return zero if the SINDARIN variable has a known value. CommandsAny 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 resultsThis 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 objectA 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 dataAfter a call to sample.next_event, the sample object can be queried for specific event data. value = sample.get_event_index(); 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.
|
