<chapter name="VINCIA User Reference"> 
 
<h2>The Antenna Shower Model (VINCIA)</h2> 
 
<h3>Overview</h3> 
 
<p> 
  The antenna shower model was initially developed as a 
  standalone plugin (VINCIA), but since Pythia version 8.300 it has 
  been incorporated into the Pythia 8 source code. 
</p> 
 
<p> 
  The shower evolution is driven by 2&rarr;3 antenna functions which 
  have DGLAP kernels as their collinear limits and eikonal factors 
  as their soft limits. They hence should exhibit improved colour coherence 
  effects relative to the old (DGLAP-based) simple shower model. 
  Likewise, the QED antenna-shower module is based on a fully coherent 
  (multipole) treatment of photon radiation patterns. For both QCD and 
  QED, the effects of parton masses (e.g., bottom and top quark masses) 
  are systematically included, and the massive 
  antenna functions have the appropriate 
  quasi-collinear limits. 
</p> 
 
<h3>Main Switches</h3> 
 
<modepick name="Vincia:nFlavZeroMass" default="4" min="2" max="6"> 
  Controls the number of flavours that will be treated as 
  massless by VINCIA, ie with massless kinematics and no mass 
  corrections. The remaining flavours will be bookkept 
  with massive kinematics and mass-corrected antenna functions. 
  Note that, even for flavours treated as massless, 
  an elementary phase-space check is 
  still made eg on all g&rarr;QQ branchings to ensure m(QQ) >= 2mQ. 
  Likewise, all heavy flavours in the initial state are forced to 
  undergo a conversion into a gluon when the evolution variable 
  reaches their mass threshold (with 
  the threshold determined by the maximum of the PDF threshold and 
  the relevant user-specifiable mass parameter given below). 
</modepick> 
 
<flag name="Vincia:helicityShower" default="off"> 
  Switch to use helicity-dependent antenna functions (or not). Only 
  meaningful when helicity information is present in the Born-level 
  events. 
</flag> 
 
<h3>Shower Starting Scales (Wimpy vs Power Showers)</h3> 
<p> 
  Similarly to PYTHIA, for processes that include at least one quark, 
  gluon, or photon  in the 
  final state, the default choice in VINCIA is to start the shower from the 
  factorisation scale used for the hard process (as given by 
  PYTHIA for internal 
  processes, or defined by the <code>scale</code> value for Les Houches 
  input),while processes 
  that do not include any such partons are allowed to populate the full 
  phase space. This behaviour can be changed by the following option, 
  which is anologous to the <code>SpaceShower:PTmaxMatch</code> option 
  in PYTHIA. 
<modepick name="Vincia:pTmaxMatch" default="0" min="0" max="2"> 
  <option value="0">Showers off processes that include at least one 
  final-state quark, gluon, or photon, are started at the factorisation 
  scale, while processes that do not include any such partons are 
  started at the phase-space maximum. 
  </option> 
  <option value="1">Showers are always started at the factorisation 
  scale. 
  </option> 
  <option value="2">Showers are always started at the phase-space 
  maximum. This option is not recommended for physics runs as it will 
  lead to unphysical double counting in many cases. 
  </option> 
</modepick> 
</p> 
<p> 
  When the first branching is limited by the factorisation scale for the 
  hard process, a 
  multiplicative factor can be applied to either increase or decrease 
  the shower starting scale relative to the factorisation scale: 
<parm name="Vincia:pTmaxFudge" default="1.0" min="0.1" max="10.0"></parm> 
</p> 
<parm name="Vincia:pTmaxFudgeMPI" default="1.0" min="0.1" max="10.0"> 
Same as above but for MPI systems, affecting the underlying event.</parm> 
<p> 
  Note that for any (combination of) choices that result in ISR 
  showers not using the factorisation scale as the starting scale, the 
  generated Sudakov factor will effectively produce leftover PDF ratios 
  in the exclusive cross sections produced by the shower. 
</p> 
 
<h3>Settings for the QCD Antenna Showers</h3> 
The settings for the QCD antenna shower modules 
are described <aidx href="VinciaQCD">here</aidx>. 
 
<h3>Settings for the QED Antenna Showers</h3> 
The settings for the QED antenna shower module 
are described <aidx href="VinciaQED">here</aidx>. 
 
<h3>Evolution with Enhanced (Biased) Kernels</h3> 
 
<p> 
  VINCIA's shower evolution can be biased to populate the multi-jet 
  phase space more efficiently and/or enhance the rate of rare processes 
  such as <ei>g&rarr;bb</ei> and <ei>g&rarr;cc</ei> splittings. It is 
  also possible to inhibit radiation (e.g., to focus on Sudakov 
  regions), by choosing enhancement factors smaller than unity. When 
  these options are used, it is important to note that the event weights 
  will be modified, reflecting that some types of events (e.g., multijet 
  events, or events with gluon splittings to heavy quarks) will be 
  "overrepresented" statistically, and others (events with few jets, or 
  events with no gluon splittings to heavy quarks) 
  underrepresented. Averages and histograms will therefore only be 
  correct if computed using the correct weight for each generated 
  event. A description and proof of the algorithm can be found in 
  <ref>MS16</ref>. Note that care has been taken to ensure that the 
  weights remain positive definite; under normal circumstances, VINCIA's 
  enhancement algorithm should not result in any negative weights. 
</p> 
 
<flag name="Vincia:enhanceInHardProcess" default="on"> 
  This flag controls whether the enhancement factors are applied to 
  shower branchings in the hard-process system. 
</flag> 
 
<flag name="Vincia:enhanceInResonanceDecays" default="on"> 
  This flag controls whether the enhancement factors are applied to 
  shower branchings inside resonance-decay systems (like Z/W/H decays) 
  that are treated as factorised from the hard process. 
</flag> 
 
<flag name="Vincia:enhanceInMPIshowers" default="off"> 
  This flag controls whether the enhancement factors are applied to shower 
  branchings in MPI systems. 
</flag> 
 
<parm name="Vincia:enhanceFacAll" default="1.0" min="0.01" max="100.0"> 
  This enhancement factor is applied as a multiplicative factor common 
  to all antenna functions, increasing the likelihood of all shower 
  branchings by the same amount. Values greater than unity thus more 
  frequently yields 
  "busy" events, with many shower branchings. Values smaller than unity 
  suppress additional branchings, yielding more Sudakov-like events. 
</parm> 
 
<parm name="Vincia:enhanceFacBottom" default="1.0" min="1.0" max="100.0"> 
  This enhances the probability for all branchings that 
  increase the number of bottom quarks (i.e., FSR <ei>g&rarr;bb</ei> 
  splittings and the corresponding ISR flavour-excitation 
  process). Note: this factor is applied on top of 
  <code>Vincia:biasAll</code>. 
</parm> 
 
<parm name="Vincia:enhanceFacCharm" default="1.0" min="1.0" max="100.0"> 
  Same as <code>Vincia:enhanceFacBottom</code> but for charm quarks. 
  Note: this factor is applied on top of <code>Vincia:biasAll</code>. 
</parm> 
 
<parm name="Vincia:enhanceCutoff" default="10.0" min="0.0" max="1000.0"> 
  Do not apply enhancement factors to branchings below this 
  scale. Intended to be used to focus on enhancements of hard branchings only. 
</parm> 
 
<h3>VINCIA Tunes</h3> 
 
<p> 
  <b>VINCIA has its own</b> set of dedicated tune presets, which can 
  be specified by the user. 
</p> 
 
<modepick name="Vincia:Tune" default="0" min="-1" max="0"> 
  <option value="-1">None. No VINCIA-specific tune parameter settings 
  will be used during initialisation.</option> 
  <option value="0">Hadronisation and MPI parameters optimised for use 
  with the VINCIA shower model, used as default VINCIA parameters 
  since PYTHIA 8.302. 
  </option> 
</modepick> 
<p><b>Note:</b> the requested tune parameters will only 
be activated when VINCIA is switched on, in order not to interfere with 
the PYTHIA settings when VINCIA is switched off. 
</p> 
<p> 
  <b>Note 2:</b> as with ordinary Pythia tune parameters, 
  the tuned parameter values will be superseded by any 
  user modifications made in the user's command file or main program. 
  This should allow sufficient flexibility to explore user 
  variations away from the tuned values. 
</p> 
<h4>Advice on Tuning</h4> 
<p> 
  Although there are obviously parameters that 
  it makes more sense to tune than others, there is no explicit 
  restriction imposed on what parameters are allowed to be present in 
  the tune file. This implies some responsibility on the part of the 
  user. 
</p> 
<p> 
  <b>As a guideline,</b> the main 
  parameters that need to be properly tuned are the 
  non-perturbative hadronisation parameters used in PYTHIA's string 
  fragmentation model. Since PYTHIA and VINCIA treat soft radiation 
  somewhat differently, there can be important differences between the 
  two in the soft region that the hadronisation model will not re-absorb 
  automatically and which therefore only a retuning can address. 
</p> 
<p> The strategy used for the default tune of VINCIA is to 
take the reference value for alphaS from the current world average 
value in the MSbar scheme, and let the effective shower scheme 
tuning be done by first translating to the CMW scheme and then 
fine-tune by modifying the renormalisation-scale prefactors used for 
shower branchings. 
</p> 
<p>An alternative (but equivalent) strategy that is often used in 
PYTHIA tunes, is to 
perceive of the value of the strong coupling itself as a tuning 
parameter. 
In this case the 
interpretation is that extracting alphaS from, e.g., event shapes, 
can be done equally well using a shower code as with more analytical 
approaches. The difference is that the alphaS value extracted with 
the shower code is in an a priori unknown scheme, defined by the 
shower algorithm. If the shower only includes LO/LL accuracy for the 
given observable(s), the extraction should be compared with other 
LO/LL extractions. This typically yields alphaS values ~ 0.13 - 
0.14. When explicit NLO corrections are included for the relevant 
observable(s), values comparable to other NLO extractions should result, 
around 0.12. 
</p> 
 
<h3>About VINCIA</h3> 
 
<p><b>The main references</b> for the current version of VINCIA are: 
<ul> 
  <li><a href="http://arxiv.org/abs/arXiv:1605.06142"> 
    VINCIA for Hadron Colliders</a>. 
  </li> 
  <li><a href="http://arxiv.org/abs/arXiv:1907.08980"> 
    Coherent Showers in Decays of Coloured Resonances</a> (for showers 
    in top quark decays). 
  </li> 
</ul> 
</p> 
 
<p> 
  <b>The name VINCIA</b> stands for "VIrtual Numerical Collider with 
  Interleaved Antennae". The naming of VINCIA is intended to allude 
  to a progression from PYTHIA - a name originating in ancient Greece - 
  to the renaissance era of Leonardo da Vinci. The logo of VINCIA is 
  the "Vitruvian Man", by da Vinci, a choice which also reflects the 
  combination of art and accuracy which is necessary to write a 
  good event generator. Classical antiquity is still indirectly 
  represented, via the namesake of the logo, Vitruvius, a 
  first-century (BC) Roman author, architect, and engineer. 
</p> 
 
<h3>Expert Settings</h3> 
 
<b>Importante Note:</b> 
the parameters in this section are intended for use only by authors or 
expert users. 
 
<h4>Sector Shower</h4> 
 
<flag name="Vincia:sectorShower" default="off"> 
  Switch to activate the sector shower in VINCIA. 
</flag> 
 
<parm name="Vincia:sectorDamp" default="0.0" min="0.0" max="1.0"> 
  In the symmetrisation over post-branching gluons that is done to 
  derive the sector antenna functions from the global ones, the 
  branching invariant with swapped gluons is nominally given by 
  <ei>yijSym = yik  = 1 - yij - yjk</ei>. If the swapped gluons are j and k 
  (and straightforwardly generalised if they are i and j) then the 
  collinear <ei>yjk&rarr;0</ei> limit does not change by adding or 
  subtracting a term of order yjk. Therefore one could equally well 
  use <ei>yijSym = 1 - yij</ei> (or something inbetween). This 
  is still guaranteed to be positive 
  definite and was indeed the choice in the original sector 
  antenna shower papers. Since the latter definition produces a value for 
  <ei>yijSym</ei> which is slightly larger than the former, the 
  corresponding 1/yijSym singularities in the antenna function are damped 
  slightly, so that larger values of the <code>sectorDamp</code> 
  parameter produces sector antenna functions which have slightly 
  smaller magnitudes outside the collinear limits. Strictly speaking 
  this choice is an ambiguity that should be varied for uncertainty 
  estimates, in which context we note that we expect it to be 
  almost entirely degenerate with variations of nonsingular terms. 
</parm> 
 
<h4>Octet Partitioning</h4> 
 
<p> 
  Within the antenna formalism, the collinear singularity of two 
  gluons j and k is 
  distributed between two neighboring antennae. One contains the 
  singularity for j becoming 
  soft, one the singularity for k becoming soft. In showers based on 
  so-called global antenna functions (as opposed to sector functions, 
  which are no longer implemented in VINCIA), the 
  two antennae share the collinear singularity, j||k, point by point in 
  phase space, and only after summing over both is the full collinear AP 
  splitting kernel recovered. 
  The parameter below controls the repartition ambiguity and gives the value 
  of "half" the gluon splitting function on its finite end. 
<parm name="Vincia:octetPartitioning" default="0.0" min="0.0" max="1.0"> 
  Gluon-collinear &alpha; parameter. Only used for final-final global 
  antennae. Note: only the default value (0) is consistent with the 
  initial-final (and 
  initial-initial) antenna functions in VINCIA. 
  Special values of interest are: 
  &alpha;=0, which corresponds to the Gehrmann-Gehrmann-de 
  Ridder-Glover 
  (GGG) partitioning, and &alpha;=1, which corresponds to the 
  Gustafson (ARIADNE) partitioning. 
</parm> 
</p> 
 
<h4>Verbose Level</h4> 
<modepick name="Vincia:verbose" default="1" min="0" max="9"> 
  Level of detail of 
  information written to standard output on what goes on inside 
  <code>VINCIA</code>. Settings different from zero and one are intended 
  for debugging purposes and hence should not be used for normal runs. 
  <option value="0">No runtime output.</option> 
  <note>Note:</note> options 1-3 only generate output when something 
  goes wrong, i.e., a check fails, etc. 
  <option value="1">Normal runtime output. Warnings and errors are 
  printed, but no additional diagnostic output is given.</option> 
  <option value="2">Enhanced runtime output. As for =1, but limited 
  additional diagnostic info is given.  Some 
  previously silent warnings are added. Also, internal VINCIA 
  diagnostics histograms are booked and filled, especially for 
  matching. These can be printed by the user at any time (e.g., after 
  a run) using the <code>VinciaPlugin::printHistos()</code> 
  method.</option> 
  <option value="3">Debug runtime output. As for =2, but as much diagnostic 
  output as possible is given for each error or warning. 
  Also, a consistency check is added 
  to each branching by reclustering the resulting momenta back using the 
  corresponding inverse kinematics map and checking that the original 
  momenta are recovered within the desired numerical 
  precision. Note: the kinematics check will slow down the speed of 
  event generation.</option> 
  <note>Note:</note> options above 4 will always generate output for 
  each event, so will cause very large amounts of output if generating 
  many events. 
  <option value="4">As for =3. And: each <code>prepare()</code> 
  and <code>pTnext()</code> call is explicitly announced, with system 
  number and restart scale printed out, respectively. </option>. 
  <option value="5">As for =4. And: momentum listings are printed for 
  each configuration that violates <code>Paccept &lt;= 1</code>. </option> 
  <option value="6">As for =5. And: each main function call is 
  explicitly announced with begin and end printed to output.</option> 
  <option value="7">As for =6. And: most function calls are explicitly 
  announced with begin and end printed to output 
  (still only partly implemented).</option> 
  <option value="8">As for =7. And: last semi-sensible level of 
  output.</option> 
  <option value="9">As for =8. And: all possible output.</option> 
</modepick> 
 
<h4>Shower Uncertainty Bands</h4> 
 
Automated uncertainty bands are not available in this version of 
the VINCIA code. 
 
<h4>Numerical Checks</h4> 
<flag name="Vincia:CheckAntennae" default="on"> 
  By default, Vincia checks antenna functions for positivity and absence 
  of dead zones. Switch to control whether to perform 
  antenna self-consistency checks or not. 
</flag> 
<modeopen name="Vincia:nPointsCheck" default="1000" min="0" max="1e6"> 
  Number of random points to check each antenna functions for positivity. 
</modeopen> 
 
<parm name="Vincia:deadZoneAvoidance" default="0.0001" min="0.0" max="1.0"> 
  During initialisation, warnings are issued if any 
  antenna functions (in dimensionless form, with the Eikonal 
  proportional to 2/y1/y2) become smaller than this number, anywhere 
  in the resolved part of phase space (away from phase-space boundaries). 
  This is to warn against spurious radiation zeroes or large 
  negative finite terms creating "dead zones", or near-dead zones, 
  in the shower. For LL showering and matching up to 
  NLO, there is in principle no problem in taking this parameter to zero if 
  so desired. However, for the NLL and higher-order matching 
  corrections, very small values of this parameter may result in weights 
  greater than unity being generated, since the corrections are 
  multiplicative and large reweighting factors may be needed 
  to "make up" for any near-dead zones at the previous branching step. 
</parm> 
 
<h4>Matrix-Element Corrections Level</h4> 
 
<word name = "Vincia:MEplugin" default = ""> 
  name of the plugin library to use for matrix element corrections. 
</word> 
 
<!-- 
<modepick name="Vincia:maxMECs2to1" default="0" min="-1" max="2"> 
Selects the order of tree-level matrix-element corrections for hard 
2&rarr;1 processes. The value <code>-1</code> is equivalent to 
switching matrix-element corrections off while <code>0</code> still 
allows to use matrix elements to select helicities at Born level. 
</modepick> 
<modepick name="Vincia:maxMECs2to2" default="0" min="-1" max="2"> 
Selects the order of tree-level matrix-element corrections for hard 
2&rarr;2 processes. The value <code>-1</code> is equivalent to 
switching matrix-element corrections off while <code>0</code> still 
allows to use matrix elements to select helicities at Born level. 
</modepick> 
<modepick name="Vincia:maxMECs2toN" default="0" min="-1" max="2"> 
Selects the order of tree-level matrix-element corrections for hard 
2&rarr;N processes. The value <code>-1</code> is equivalent to 
switching matrix-element corrections off while <code>0</code> still 
allows to use matrix elements to select helicities at Born level. 
</modepick> 
 
 <modepick name="Vincia:maxMECsResDec" default="0" min="-1" max="2"> 
 Selects the order of tree-level matrix-element corrections in 
 resonance decays. The value <code>-1</code> is equivalent to 
 switching matrix-element corrections off while <code>0</code> still 
 allows to use matrix elements to select helicities at Born level. 
 </modepick> 
 
 <modepick name="Vincia:maxMECsMPI" default="-1" min="-1" max="1"> 
 Selects the order of tree-level matrix-element corrections applied to 
 the hardest MPI in the event. The value <code>-1</code> is equivalent to 
 switching matrix-element corrections off while <code>0</code> still 
 allows to use matrix elements to select helicities at Born level. 
 </modepick> 
 
 <flag name="Vincia:matchingFullColour" default="on"> 
 <option value="off">Leading Colour. 
 </option> 
 <option value="on">Full Colour. Include the full colour structure of the 
 matched matrix elements, absorbing the subleading-colour pieces into 
 each leading-colour one in proportion to the relative sizes of the 
 leading-colour pieces. This procedure effectively diagonalises the 
 full colour matrix and guarantees positive-weight corrections. 
 </option> 
 </flag> 
 
--> 
 
</chapter> 
