# Draft

(Difference between revisions)

## Current revision

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

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


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

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. In this case the settings don't need to be present in the order file. The OLE must add these default settings in the contract (this is the fine print in the contract, it has to be there so the OLE can decline responsability if the MCP is not happy about them). 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 order file

AmplitudeType CH_SUMMED
QCD_scheme Dreg
model_file my_favorite_model_in_LH_format.slh
subdivide_subprocess yes

2 -> 3 21 21 6 -6 21
2 -> 3 1 -1 6 -6 21
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

AmplitudeType CH_SUMMED
QCD_scheme Dreg                                 | 1
model_file my_favorite_model_in_LH_format.slh   | 1
subdivide_subprocess yes                        | 1

2 -> 3 21 21 6 -6 21                  | 2 13 35
2 -> 3 1 -1 6 -6 21                   | 1 29
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). All default parameters, which were not specified in the order, are written down in the contract by the OLE.

# example contract file
# contract produced by OLE UNHAPPY_OLE

AmplitudeType CH_SUMMED                         | -2 note: unsupported type of amplitudes
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

2 -> 3 21 21 6 -6 21                  | 0 note: Sorry, OLE don't support massive quarks
2 -> 3 1 -1 6 -6 21                   | 0 note: Sorry, this process is not implemented in OLE UNHAPPY
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 :

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.

### Init

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.

### EvalSubprocess

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.

## Example

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 --

open("order.dat")
open("contract.dat")
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)
}


The run time OLE could be a library of compiled code. The engine code could look like

-- somewhere inside the RTOLE 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(...)

...

}
}