VINCIA Matching Parameters
(nb: see the section on Initialization for how to set and change parameters.)

On/Off

flag  Vincia:matching   (default = on)
Global switch for matching on/off. When on, the switches and parameters below control the strategy and order to which matching is carried out, to the extent the relevant matrix elements are available. Note that this matching is only available for the VINCIA showers (not for the internal PYTHIA 8 showers), and so the main VINCIA on/off switch must also be set to on, Vincia = on, when using VINCIA matching, see the section on the VINCIA shower.

Matching Strategy

mode  Vincia:matchingStrategy   (default = 1; minimum = 1; maximum = 3)
Selects which strategy to use for the matching. The default is the multiplicative strategy, which is the only one so far available in the distributed version.
option 1 : Multiplicative (a.k.a. merging, or branching reweighting).
option 2 : Hybrid. Not implemented, placeholder only.
option 3 : Additive (a.k.a. event reweighting). Not implemented, placeholder only.

Matching Level

Matching Order

mode  Vincia:maxMatchTree   (default = 3; minimum = 0; maximum = 4)
Selects the order of tree-level matching (sometimes called Leading Order matching). The value should be interpreted as counting the total number of powers of alphaS beyond the Born. I.e., for the basic process X, setting this switch to 2 would invoke tree-level matching up to and including X+2 partons, to the extent the relevant matrix elements are available in the code. The value 0 is equivalent to switching matching off.

mode  Vincia:maxMatchLoop   (default = 0; minimum = 0; maximum = 0)
Placeholder for a similar switch for one-loop matching. Note that the one-loop order cannot be chosen higher than the tree-level order set above. The value should be interpreted as counting the total number of powers of alphaS beyond the Born. Thus, setting this switch to 0 is equivalent to switching off one-loop matching, (since the first one-loop correction arises at one power beyond the Born). Setting it to 1 invokes one-loop matching of the Born process, 2 extends the 1-loop matching to X+1 partons (2 powers beyond the Born), etc. As for the tree-level switch, the matching will only take place to the extent the relevant matrix elements are available in the code.

Color Depth

mode  Vincia:matchingColorDepth   (default = 1; minimum = 0; maximum = 1)

option 0 : Leading Color. Only include matching to leading-color matrix elements.
option 1 : Full Color. Include the full color structure of the matched matrix elements, absorbing the subleading-color pieces into each leading-color one in proportion to the relative sizes of the leading-color pieces. This procedure effectively diagonalizes the full color matrix and has been checked to result in positive-definite corrections for all the matrix elements so far implemented in large scans (order of 1 million points) over phase space.

Matching Regulator

We use the term matching regulator to refer to a generic sharp or smooth dampening of the ME corrections as one crosses into a specified region of phase space. The purpose of this is to restrict the matching to regions of phase space that are free from subleading logarithmic divergences in the matrix elements. This is familiar from the CKKW and MLM approaches, where the matching scale is imposed as a step function in pT, with full ME corrections above that scale and no ME corrections below it. We explore a few alternatives to this approach.

mode  Vincia:matchingRegOrder   (default = 2; minimum = 0; maximum = 4)
Choose starting order from which matrix element corrections are regulated.
option 0 : Off. Matrix element corrections are not regulated at all. Not advised for production runs, but can be useful for theory studies.
option 1 : On, starting from 1st order in QCD. This would normally be overkill since the LL shower exactly reproduces the 1st order matrix-element singularities - the first-order correction should therefore normally be free of divergencies and should not need to be regulated.
option 2 : On, starting from 2nd order in QCD. This is the recommended option for the additive matching strategy. The 2nd-order matrix element correction generally contains subleading logarithmic divergences which do not correspond exactly to those generated by the shower. Since these divergencies are not resummed, a regulator is needed to keep the generated event weights from diverging, starting from this order.
option 3 : On, starting from 3rd order in QCD. This is the recommended option for the multiplicative and hybrid matching strategies. Since the matrix-element corrections are exponentiated in those approaches, the subleading divergencies in the 2nd-order corrections are effectively resummed. In principle, this should work to arbitrary order, but due to the LL nature of the shower in other respects, it appears from empirical studies that a matching scale is still needed starting from 3rd order even in the multiplicative case.
option 4 : On, starting from 4th order in QCD. Not recommended for production runs, but can be useful for theory studies.

mode  Vincia:matchingRegShape   (default = 1; minimum = 0; maximum = 1)
When Vincia:matchingRegOrder >= 1, choose the functional form of the regulator. (See below for how to modify the choice of Q and Qmatch.)
option 0 : Step function at Q=Qmatch, i.e.,


option 1 : Suppress the shower-subtracted ME corrections by a function that is unity above Q2 = 2*Q2match, zero below Q2 = Q2match/2, with a simple interpolation (logarithmic in Q2) between those scales, i.e.,

Matching Scale

The choices described here affect how the scales Q and Qmatch in the regulators described above are computed.

mode  Vincia:matchingScaleType   (default = 1; minimum = 1; maximum = 2)
When Vincia:matchingRegOrder >= 1, choose argument of the regulator function (i.e., Q in the equations listed under Vincia:matchingRegShape).
option 1 : Impose matching scale in the type 1 evolution variable, Q2=4*pT^2. The smallest pT scale of the current branching and the color neighbor on either side (if any) is used.
option 2 : Impose matching scale in the type 2 evolution variable, Q2=4*pT^2. The smallest invariant mass of the current branching and the color neighbor on either side (if any) is used.

flag  Vincia:matchingScaleIsAbsolute   (default = false)
Selects whether the user wants to input the value of Qmatch either by giving an an absolute number in GeV or by giving a ratio with respect to the hard scale.
option false : Relative. The matching scale is determined automatically in relation to the hard scale in the process (e.g., the Z mass) by the factor Vincia:matchingScaleRatio below. This is the default option and the one recommended for non-experts. It should allow a wide range of processes to be considered without having to manually adjust the matching scale.
option true : Absolute. The matching scale is set by the value Vincia:matchingScale (in GeV). Care must then be taken to select a matching scale appropriate to the specific process and hard scales under consideration. For non-experts, the relative method above is recommended instead.

parm  Vincia:matchingScaleRatio   (default = 0.05; minimum = 0.0; maximum = 1.0)
When Vincia:matchingScaleIsAbsolute == false (default), this sets the ratio of the matching scale to the process-dependent hard scale; inactive otherwise. Since the unresummed logarithms depend on ratios of scales, it is more natural to express the matching scale in this way than as an absolute number in GeV. Note that this parameter should normally not be varied by more than a factor of 2 in either direction. The default value has been chosen so as to allow one order of magnitude between the hard scale and the matching scale. Setting it too close to unity will effectively switch off the matching, even at high scales. Settings around 0.01 and below risk re-introducing large unresummed logarithms in the matching coefficients.

parm  Vincia:matchingScale   (default = 20.0; minimum = 0.0)
When Vincia:matchingScaleIsAbsolute == true, this sets the absolute value of the matching scale, in GeV; inactive otherwise. Care must be taken to select a matching scale appropriate to the specific process and hard scales under consideration.

Event Weights

Care has been taken to ensure that all events generated by VINCIA have weights which are positive and equal to unity. Indeed, this property is central both to the shower and to the multiplicative matching scheme. Ordinary runs should therefore produce a simple set of unweighted events, equivalent to normal Pythia 8 output.

However, Vincia does allow for negative weights and/or weights greater than unity to be generated, for instance if additive matching is used and/or if settings have been chosen so extreme that large negative or positive corrections become unavoidable, or in case the future subleading-color corrections turn out to require the generation negative weights. In these cases, warnings will be printed to the standard output. If changes to the event weight are made, these are properly bookkept and the final weight is accessible after the event has been fully generated through the weight() method in the Vincia plugin. For instance, if the VinciaPlugin object is called vincia the generated event weight can be accessed by

vincia.weight();

Convenient yes/no shorthands for checking whether any negative weights w < 0 and/or any non-unity weights abs(w) > 1 have been generated at all (during the current run) are provided by the methods

bool vincia.negativeWeightOccurred();
bool vincia.nonunityWeightOccurred();

Note that Vincia's weights fully include any non-unity input weights associated with the event from Pythia (normally, Pythia's weights are unity, but when using external events, e.g., from LHEF files, these can in principle come with non-unity weights). The weight Vincia started from is not modified and remains accessible through Pythia's own info.weight() method.

Technical Parameters

parm  Vincia:headRoomFactor   (default = 1.5; minimum = 1.0; maximum = 10.0)
A multiplicative factor applied to the trial generator to prevent P > 1 from occurring during trial accept/reject stage. (When matching is switched off, this factor is set to unity.) Note that, the better the shower approximation, the smaller this factor can be chosen. The default value is chosen to work optimally with the ARIADNE kinematics map. For other kinematics maps, higher settings may be needed to avoid P > 1 warnings. Note, however, that the code automatically increases this number (in 10% steps) when P > 1 warnings are encountered, so such warnings should gradually disappear for long runs, at the expense of slower running.

MadGraph Interface

A small library of matrix elements obtained with MADGRAPH (MG) are included with the standard VINCIA release. (In the future, matrix elements for additional processes will be available for download from the VINCIA homepage.) Through its MG interface, VINCIA is able to match to these matrix elements during the shower evolution.

flag  Vincia:MGInterface   (default = on)
The MGInterface must be switched on for matching to work properly.

Note: see the section on Useful References for additional references to include when using the matrix elements provided by this interface.

Note 2: parts of the MADGRAPH code (specifically the HELAS libraries) are needed at runtime to evaluate the MADGRAPH matrix elements. The Makefile distributed with VINCIA will automatically attempt to download and install the MADGRAPH standalone tarball for you, if it doesn't find it in the expected location, and will then compile the relevant libraries from it. If this fails, we recommend having a look in the Makefile before contacting the authors. Large parts of the Makefile have been made user-editable in hopefully straightforward ways, and it may be possible for you to solve the problem by trivial editing.

Importing new matrix elements from MadGraph

The procedure for including a new matrix element is not intended for general users at this point, but is documented here for reference:

The MADGRAPH matrix elements included with VINCIA are located together with the actual interface code in VINCIA's MGInterface/ subdirectory. They are ordinary MADGRAPH matrix element routines, which have been renamed and modified slightly for use by VINCIA. Most of this conversion is done automatically, by a script. Implementing new matrix elements should therefore be fairly trivial, as long as the final state corresponds to something that VINCIA can actually generate. (E.g., implementing matrix elements for DIS or hadron-collider processes will not suddenly make VINCIA able to handle such cases, since the shower is not yet developed for that.)

Procedure:

Last modified: