From Wiki Les Houches 09

(Difference between revisions)
Jump to: navigation, search
(contract file)
(contract file)
Line 100: Line 100:
  # example contract file
  # example contract file
  # contract produced by OLP UNHAPPY_OLE
  # contract produced by OLE UNHAPPY_OLE
  QCD_scheme Dreg                                | -2 note: supported schemes are t'HV   
  QCD_scheme Dreg                                | -2 note: supported schemes are t'HV   

Revision as of 11:53, 13 June 2009

This is a working draft for an interface between one-loop amplitude programs and monte carlo programs.


Goal of the interface

The goal of the interface is to facilitate the transfer of information between one-loop programs (which we will call one-loop provider OLP or one-loop engine depending on whether we mean the method/work (Golem, Rocket, Helac one-loop, BlackHat, ...) or the actual run time entity) which provide one-loop matrix element and the program the does the integration over the phasespace (which we will call MC).

What this interface is not

The goal of this interface is not to constraint OLP to a certain way of computing one-loop amplitude. The goal is to provide a platform for the combination of compatible results.

Model of the interaction between MC and OLE

The model of the interaction between the MC and OLE assumes two phases which we will call "initialization" and "run time".

1. Initialization

During this phase the MCP sets up the OLE. This means setting up the parameters and fixing options that are offered by the OLP

  • model parameters
  • operating mode, for example which approximation (leading color, massless b's, ...)
  • schemes (QCD, EW renormalization, factorization)

2. Run time

During this phase the MCP queries the OLE for the value of a virtual matrix element.

Implementation proposal

This section outlines a proposal for the implementation of the interface model presented above. The aim is to make it easy to implemeent it in all common programming language. The functions will be called by the MCP and executed by the OLE. The name of the function and its implementation can be chosen by the OLP (although sticking to the name in this wiki would be convenient), the main point being to provide a function that satisfies the interface.

In the easiest case of merging two programs written in the same language, the connection between the caller (the MCP) and the receiver (the OLE) can be easily achieved by linking the rogram together. In more difficult cases with mixed languages or special environments a bridge program or transmission protocol will have to be put in place. This is however not the topic or concern of this proposal, here we only want to ensure that the end point of these bridges will be the same.

Initialisation phase

In this phase the MCP creates a file that contains the information about the subprocesses it will need to perform the computation. We will call this file the "order". This file is then read by the OLE and it creates a new file with the agreement about how to link the MCP and OLE at runtime is provided. We will call this file a "contract". Lines starting with a # character are treated as comments. In this section we call a subprocess both the partonic subprocesses and any component of if in some basis.

order file

the order file contains the information needed for the OLE to declare whether or not it can provide the subprocess the MCP wants.

The first part of the file contains some general settings.

The second part contains the list of the subprocesses the MCP needs. Each line is of the form

[TYPE] [in] -> [out] [[PDG]...] [...]

where [TYPE] describes which type of subprocess the MCP want. For example one could ask for color and helicity summed amplitudes. [in] is the number of particles in the initial state. [out] is the number of particles in the final state. [PDG] is the pdg code of the particle. The first entries are for the initial states, then comes the final state particles.

The settings that a OLE should (have to?) provide are

  • QCD_scheme : the scheme for the QCD renormalization
  • EW_scheme : the scheme for the EW renormalization

OLE can provide more settings. They have to be documented. We encourage OLP to submit new settings to the WIKI in order to avoid having the same optional setting called differently by different OLP.

  • model_file : the model file (in LH format) from which parameters have to be read
  • mode : the operating mode of the OLE

The OLE can provide defaults for its settings. The OLE can define new settings. If a setting is mandatory but has not been provided, the OLE should issue an error message and write only this error message in the contract file.

Here is an example of a order file

# example contract file

QCD_scheme Dreg
mode leading color
model_file my_favorite_model_in_LH_format.slh
subdivide_subprocess yes
CH_SUMMED 2 -> 3 21 21 6 -6 21
CH_SUMMED 2 -> 3 1 -1 6 -6 21
CH_SUMMED 2 -> 3 1 21 6 -6 1

contract file

The OLE reads the order file and creates its "answer" in the form of a contract file. The contract file is basically a copy of the order file, but with information from the OLE appended at the end of each (non content-free) line. The OLE answer is separated from the MCP "request" by a "|" character. The answer of the OLE should give are explained in the following paragraphs.

For settings, the answer should be appended as follows. 1 if the setting is supported and the supplied arguments are correct. Errors are coded as follows: -1 if the option is not supported, -2 if the option is supported but the parameter is not recognized/valid.

For subprocesses, the answer should be the number of separate contributions that the OLE can compute that add up to the required subprocess, followed by an integer label that identifies each of these contributions. This allows the multi-channel integrator (if present) to take advantage of importance difference between the provided subcontributions. The integer label will be use at run time to identify the subprocesses. OLE that provide this kind of separation might also provide a single subprocess that is the sum of all contributions. Whether or not to return the contributions separately could be set using a setting subdivide_subprocess

Example contract file

# example contract file
# contract produced by OLE HAPPY_OLE

QCD_scheme Dreg                                 | 1  
mode leading color                              | 1
model_file my_favorite_model_in_LH_format.slh   | 1
subdivide_subprocess yes                        | 1

CH_SUMMED 2 -> 3 21 21 6 -6 21                  | 2 13 35
CH_SUMMED 2 -> 3 1 -1 6 -6 21                   | 1 29
CH_SUMMED 2 -> 3 1 21 6 -6 1                    | 3 8 23 57

It would be useful if the OLE could provide some help in case of failure (like listing the parameter that are accepted).

# example contract file
# contract produced by OLE UNHAPPY_OLE

QCD_scheme Dreg                                 | -2 note: supported schemes are t'HV  
mode leading color                              | -2 note: OLE UNHAPPY don't have a "leading color" mode 
model_file my_favorite_model_in_LH_format.slh   | -2 note: could not find file "my_favorite_model_in_LH_format.slh"
subdivide_subprocess yes                        | -1 note: unknown setting

CH_SUMMED 2 -> 3 21 21 6 -6 21                  | 0 note: Sorry, OLE don't support massive quarks 
CH_SUMMED 2 -> 3 1 -1 6 -6 21                   | 0 note: Sorry, this process is not implemented in OLE UNHAPPY
CH_SUMMED 2 -> 3 1 21 6 -6 1                    | 0 note: Sorry, too hard for OLE UNHAPPY

A description of the difference between the different contributions could be useful :

CH_SUMMED 2 -> 3 21 21 6 -6 21                  | 2 4 25 note: contributions are leading_color, sub_leading_color

Run time phase

To start the run time phase, the OLE might need to be reminded of the contract it committed to (this is the case for programs that dynamically generate their evaluation structure as opposed to libraries of generated code). To initialize the OLE for the run, the function Init has to be called by the MCP. After this the MCP can start querying the OLE fr the subprocesses. This is done using the function EvalSubProcess.


the function Init should be passed an character sting that contains the name of the contract file. The function returns 1 if the initialization is successful, 0 if not.


The parameters to be passed to the EvalSubprocess function are (to avoid confusing, please use this order)

  • the integer label of the subprocess
  • the address of the start of an array containing the components of the momenta. The momenta are placed in a on dimensional array. The first component is the energy of the first particle, then x, y, z components of this momentum and its mass, then comes the second momentum energy, x, y, z, m etc... The mass is defined as E^2-x^2-y^2-z^2 but is provided for numerical reasons. The unit is Gev. Both incoming and outgoing momenta have a positive energy. This means that the array will contain n*5 double precision numbers.
  • the renormalization scale as a double precision number, in Gev.
  • the strong coupling double alpha_s
  • the weak coupling alpha_EW
  • the address of a the array where the result is to be put. The length and the content of this array is to be documented by the OLP. We will define here one possibility, if the OLP departs from it, it should be clearly documented.
Pole2, Pole1, Pole0, Born

where PoleN is the real part of the coefficient of the pole eps^(-n) of the interference Re(A_1 A_0^*). eps is defined as D=4-2 eps. Born is the born cross section for the subprocess A_0 A_0*. The size of the array has to be documented by the OLP.

The result array can be used to pass additional parameters to the OLE. If needed, some values can be put in the result array, the OLE reads them and replace them with the result once it has finished the evaluation.


To simplify the example, we will assume that the MCP and OLE can talk to each other using function call.

Initialisation phase

A MCP that generates code for a given NLO process first creates the order file

-- somewhere inside MCP code -- 
find out what settings are appropriate for the process

write the settings to the file order.dat

find out what subprocess is needed for the process in consideration

for ( all subprocesses)
   write the subprocess info to    order.dat

Then, the OLE is invoked and reads the order file

-- somewhere inside OLE code -- 

read(next line)
while (next line is a setting){
   if (setting is known){
       if (parameter is ok){
            apply setting
            copy input line to "contract.dat"
            append "| 1 " 
       } else {
            copy input line to "contract.dat"
            append "| -21 "  
            possibly append explanation why it does not work 
   } else {
      copy input line
      append "| -1 " 
      append information


while (next line is a subprocess specification){
   if ( I can provide the subprocess ){
      apply setting
      copy input line
      append "| " 
      append number of contributions
      for (number of separate contributions ) do {
           append label  
   } else {
      copy input line
      append "| 0 " 
      append information/apologies

Run time phase

The run time MC program RTMCP is started (it need not be the same program as the MCP, it could be the program resulting from compiling the code generated by the MCP). The RTMCP has to initialize the OLE.

 -- somewhere inside RTMCP code

initialize RTMCP for process ...

call Init("contract.dat")

while( not enough statistics ) {
    choose a subprocess
    choose a phasespace point
    prepare the arguments for  EvalSubprocess
    call EvalSubprocess(ProcessLabel,Momenta,MuScale,AlphaS,AlphaEW,ResultArray)

An example of OLE could be a library of compiled code. The engine code could look like

-- somewhere inside the OLE code 

Init(ContractFilename) {
    do whatever the library need to do for initialization, probably nothing  

EvalSubprocess(ProcessLabel,...) {
   switch ( ProcessLabel){
      case 15 :  prepare the arguments for the library call
               call CompileCodeForProcess15(...) 
      case 23 :  prepare the arguments for the library call
               call CompileCodeForProcess23(...) 


In an OLE that generate the evaluation structure dynamically, we would see something along the lines of

-- somewhere inside the OLE code 

Init(ContractFilename) {
    for ( all subprocesses in the contract file )    
       create runtime structure
       store it somewhere and be ready to evaluate it when the corresponding process label is asked

EvalSubprocess(ProcessLabel,...) {
   switch ( ProcessLabel){
      case 15 :  prepare the arguments for the run time structure
               call RunTimeStructure15(...) 
      case 23 :  prepare the arguments for the run time structure
               call RunTimeStructure23(...) 


Possibly useful links


Personal tools