= The WHIZARD / O'Mega interface (C. Speckner) = == Overview == The WHIZARD / O'Mega interface generates the model files necessary for the inclusion of a FeynRules model into the WHIZARD / O'Mega framework. All versions of WHIZARD / O'Mega >= 1.92 are supported. == Usage: all versions == As all other interfaces, the WO interface is invoked by calling {{{WriteWOOuput}}}. Three syntax variants are admissible: 1. {{{WriteWOOutput[Lagrangian, Options]}}} 2. {{{WriteWOOutput[{LagrangianList}, Options]}}} 3. {{{WriteWOOutput[Null, WOVertexList->{VertexList}, Options]}}} Version 1. operates on a single Lagrangian, while 2. operates on a list of Lagrangians and 3. takes a list of FeynmanRules as an argument. The following options are available: * {{{WOVertexList}}}: If {{{=!= Null}}}, this is interpreted as a list of Feynman rules and overrides any Lagrangian (or -list) specified (in this case, {{{Null}}} is accepted as first argument). Default: Null * {{{WOModelName}}}: The name by which the model will be identified in WO. Note that all models for W1.9x have to start with "fr" (e.g. {{{WOModelName->"fr_sm"}}}) if they are to be picked up by WO1.9x without user intervention (no such restriction exists for W2). Beware that the interface may modify this name if it doesn't fit into the WO naming schemes --- double check the generated messages to be sure. Default: derived from the FR model name * {{{WOMaxNcf}}}: Upper limit on the number of color flows which the generated code will be able to handle (essentially n_8 - n_3 / 2, where n_8 is the maximum number of external octets and n_3 that of external triplets). Irrelevant for W2; also, the technically inclined user can change this after running the interface in {{{f90_modellname_Col.ml}}}. Default: 4 * {{{WOGauge}}}: The following gauges are available: * {{{WOUnitarity}}}: Unitarity gauge (default) * {{{WOFeynman}}}: Feynman gauge * {{{WORxi}}}: Rxi gauges. In this case, you __must__ define a parameter taking the role of \xi and pass it to the interface via {{{WOGaugeParameter}}} (see below). * {{{WOGaugeParameter}}}: The parameter which takes the role of \xi in the Rxi gauges, can be either a string or a symbol. Note that this parameter is automatically added to the parameter list if WOAutoGauge is set to {{{True}}}. Default: "Rxi" * {{{WOWhizardVersion}}}: Select the WO version for which you want to generate code. Possible choices: * {{{"1.92"}}}: WO 1.92 * {{{"1.93"}}}: WO 1.93 - 1.95 * {{{"2.0" }}}: WO 2.0 (default) * {{{WOVerbose}}}: Verbose output. At the moment, this gives detailed information on skipped vertices. Default: False * {{{WOAutoGauge}}}: Automagically assign goldstone boson masses and add the gauge parameter to the parameter list (in the case of Rxi gauge). Default: True * {{{WOMaxCouplingsPerFile}}}: The maximum number of couplings written into a single FORTRAN file. Reduce this number if you run into trouble compiling the generated code. Default: 500 * {{{WORunParameters}}}: A list of all parameters which are recalculated when \alpha_s changes. Without effect for WO1.9x output. Default: {G, aS} * {{{WOFast}}}: Set this to False to enable more time consuming checks for known lorentz structures if you have trouble with skipped couplings. Default: True * {{{Output}}}: The output directory which will contain the generated model files. Default: derived from the FR model name It is wise to '''check the messages the interface generates''' while it runs; i these will inform you about any unidentified vertices that have been skipped as well as of most other noteworthy caveats concerning the generated code. == Usage: WO 1.9x == In order to use the interface with WO 1.9x, the build system of WHIZARD must be patched and the model files copied to the proper locations in the tree. This is taken care of by the script called {{{inject}}} which is created by the interface in the output directory. The basic usage is (from within the output directory): {{{./inject [options] path_to_whizard}}} Running {{{./inject --help}}} will give a full overview over the supported options. After "injecting", the model is available in WHIZARD and will behave like the stock ones. However, some caveats exist for the unwary, so '''pay attention to the scripts output messages''' and be sure to '''read through this list carefully''': * The inject script has been designed to avoid any accidental change of existing data. Therefore, if a FeynRules model of the same name already exists, it will not be overwritten by default (the script will inform you if a file is being skipped though). To enforce overwriting of existing files, use the {{{--force}}} option. * If the number of distinct couplings changes significantly, the number of generated FORTRAN files may change. This can lead to problems with spurious files from a previous run being present in the WHIZARD tree, potentially wreaking havoc on the WHIZARD compilation. The script will inform you of such conflicts, and you can then rerun it with the {{{--cleanup}}} option to remove the conflicting files automatically. * Be sure to reconfigure WHIZARD (rerun the configure script) after injecting a model. Also, if the compilation fails, a {{{make clean}}} or {{{make realclean}}} in the WHIZARD tree can help to put a borked tree into a sane state again (take care as those remove your input files, so make copies before). * In order for the model to be picked up by WHIZARD, the WO mode name must start with "fr". This is taken care of automatically if the interface assigns it, but if you reset it via {{{WOModelName}}}, it is your responsibility to pick a proper name. * Writing multiple models to one output directory is possible and supported. == Usage: WO 2.0 == WO 2.0 and above natively support the addition of new models without recompiling WHIZARD. More specifically, WHIZARD looks for any model specific files first in the uses local installation tree {{{${HOME}/.whizard}}} and the in the global installation tree {{{${PREFIX}}}}. Therefore, in order to use an external model with WO2, the O'Mega binaries and FORTRAN libraries must be compiled and installed in the proper directory together with the WHIZARD model definition. To the end, the WO interface creates a standard autotoolized (don't worry if you don't know what this means) {{{./configure; make install}}} type build system in the output directory. The build system supports multiple models in one output directory. To use it, you must perform three steps (in the output directory): 1) Configuration {{{./configure WO_CONFIG=path_to_the_wo_binaries --prefix=installation_prefix}}} Both options are optional. {{{WO_CONFIG}}} can be used to specify the path to the WHIZARD binaries (otherwise, they are searched for in {{{${PATH}}}}), and {{{--prefix}}} sets the installation prefix for the model files ({{{~/.whizard}}} by default). 2) Compile {{{make clean; make}}} This compiles the O'Mega binary and the FORTRAN libraries. While not strictly necessary, the {{{make clean}}} step is good practice to make sure no leftovers from previous compiles disturb the result. 3) Install {{{make install}}} Install the model files in the installation prefix. If the model is installed either into {{{~/.whizard}}} or into the installation prefix of WHIZARD, it will be found by WHIZARD without any further action. In all other cases, the path to the prefix must be supplied to WHIZARD at runtime via the {{{--localprefix installation_prefix}}} option. == Notes & caveats for the unwary: all versions == * The interface will refuse to write output to a directory which already contains model files generated for a different WO version. * The list of supported operators is essentially limited to operators of dimension <= 4 together with some higher dimension ones (e.g. three point graviton-x-x couplings in ADD like models). This list will be expanded in the future. * If vertices are skipped due to unidentified Lorentz structures, the option {{{WOFast -> False}}} can be used to enable more expensive checks for known operators. * Color structures are implicit in O'Mega and derived from the SU(3) representations of the particles at the vertex, limiting the currently available color structures. However, the interface will complain if an unsupported structure is encountered. * For ADD-like graviton-x-x couplings, the mass of the particles couplings to the graviton __must__ be declared as symbolic values (which, however, can be external parameters) if the vertex is to recognized. * Make sure that the gauge used in the definition of the model matches that used by the interface (c.f. {{{WOGauge}}}). NB: If you allow the interface to automatically assign the goldstone boson masses via {{{WOAutoGauge}}} (the default), then any Feynman gauge model can be used for the Rxi gauges as well, provided that you define a parameter for \xi (see WOGaugeParameter above). * Complex parameters are automatically split into real and imaginary parts (with {{{_r}} resp. {{{_i}}} appended to the parameter name). == Notes & caveats for the unwary: WO 1.9x == * In order to be picked up by WHIZARD automatically, the model name must start with {{{fr}}} (c.f. the above description of {{{WOModelName}}}). * If you want to simulate processes with many external colored particles (e.g. 5+ gluons), you must increase {{{WOMaxNcf}}} from its default (see above). * WO 1.9x does not support running \alpha_s. == Notes & caveats for the unwary : WO 2.0 == * Accepted complex internal parameters are currently limited to polynomials of complex parameters. * All parameters given in the {{{WORunParameters}}} list as well as all vertex factors depending on those are recalculated when \alpha_s is run. If you want to have \alpha_s running at some vertices and constant at others (e.g. gluino vertices), you can do so by defining an alias for \alpha_s as a derived parameter.