---------------------------------------------------------------------------- This README is a part of the VINCIA plug-in to the PYTHIA 8 generator. Copyright (C) 2019 P. Skands VINCIA is licenced under the GNU GPL version 2. Please respect the MCnet Guidelines for Event Generator Authors and Users, http://www.montecarlonet.org/GUIDELINES Contents: * Manual * Download & Install * Example programs * Update notes ---------------------------------------------------------------------------- Manual / HTML User Reference: The switches and parameters of VINCIA are documented in the code's HTML User Reference Manual, Vincia.html, which is included together with the code, in the htmldoc/ subdirectory. The manual is also available on the web at: http://vincia.hepforge.org/current/htmldoc/ ---------------------------------------------------------------------------- Download & Install: We highly recommend consulting the HTML User Reference above, which contains more explicit installation instructions, including some options and troubleshooting information. Here, we only give a very condensed summary of the steps required for a default standalone installation. Prerequisites: * Make sure you have a compilation environment with mutually compatible F77 and C++ compilers, since VINCIA uses both of those languages. (In recent versions of gcc, for instance, this should be automatic, since gfortran is part of the gcc installation. If you experience problems, further instructions can be found in section on Installation and Linking in the HTML User Reference.) Installation: 1. Download, configure, and make PYTHIA 8. See http://www.thep.lu.se/~torbjorn/Pythia.html Use the following compatibility table to ensure that your VINCIA and PYTHIA versions are compatible ====================================================================== With Use PYTHIA versions VINCIA versions Comments ---------------------------------------------------------------------- 8.240 - 8.243 2.301 - 2.302 Change in Pythia MergingHooks 8.240 2.204 - 2.205 New Pythia shower base class 8.230 - 8.235 2.201 - 2.202 Removed calls to initPtr() 8.226 2.200 - 2.202 New initialisation 8.212 - 8.223 2.000 - 2.001 Vincia ISR; new Pythia pTnext() 8.200 - 8.210 1.200 - 1.202 New structure for Pythia 8.2 8.183 - 8.185 1.102 - 1.103 New TimeShower::prepare() 8.180 1.101 - 1.103 New Pythia include/ structure 8.176 1.100 Pythia change to Event record 8.175 N/A No compatible Vincia version 8.170 N/A Pythia fragmentation bug 8.162 - 8.165 1.028 - 1.029 New Pythia::init() 8.160 N/A (crashes) Pythia initialization bug 8.145 - 8.157 1.025 - 1.027 CoupSM -> Couplings 8.135 - 8.140 1.024 New prepare() function 8.135 1.019 - 1.023 Dropped static dependencies 8.100 - 8.130 1.000 - 1.018 ====================================================================== 2. Download the VINCIA plug-in, vincia-N.N.NN.tgz (with N.N.NN being the version number), from the VINCIA homepage: http://vincia.hepforge.org Untar the tarball (assuming you downloaded version N.N.NN): tar -xvzf vincia-N.N.NN.tgz 3. Go to the thus created subfolder vincia-N.N.NN/ and run "./configure" (use "./configure --help" to see configuration options), then run "make": cd vincia-N.N.NN/ ./configure --help ./configure [options] make Note: it is important to tell VINCIA where your PYTHIA 8 library and data files are, as well as any additional packages you want to link to, such as ROOT 6 or FASTJET. Use ./configure --help to see how to do this and/or set the PYTHIA8DATA environment variable. See also the VINCIA HTML manual for additional advice and hints on installation and linking. 4. Move to the examples/ subfolder ("cd examples") and run "make" there. The test program vincia01 should now be ready to run. It uses a command file vincia01.cmnd (similar to those of other PYTHIA8 example files) which can be edited to change settings and parameters. See the HTML User Reference for documentation of these. cd examples/ make vincia01 ./vincia01 5. You don't have to stick to VINCIA's example programs. Modifying an arbitrary PYTHIA 8 main program (e.g., your own) to run VINCIA requires adding two lines of code: 1) #include "Vincia.h", 2) construct the VinciaPlugin object, described in the example programs and in the HTML User Reference. Finally, 3) you need to replace the call to Pythia::init() by one to VinciaPlugin::init(). To compile and run, you will of course need to make sure that the VINCIA headers and source codes are available at compile time (for instance by using the default Makefile which assumes that the source and header files are in the src/ and include/ subdirectories of the current directory, respectively), and you will need to make sure that the XML file set is available at run-time (default location share/Vincia/xmldoc/). See "./configure --help" and the HTML User Reference for advanced installation options. ---------------------------------------------------------------------------- VINCIA example programs: The following programs are currently included, to illustrate how to link and run VINCIA, and to illustrate various common usage tasks, such as computing event shapes at LEP, interfacing ROOT, or calculating jet rates with FASTJET: ===== LEPTON COLLIDER EXAMPLE PROGRAMS ========================================= - vincia01.cc : simple Z -> hadrons example at LEP - vincia02.cc : simple WW -> hadrons example at LEP2 - vincia03-root.cc : illustrates tuning to event shapes and particle rates, using runtime ROOT diplays and comparisons to LEP data - vincia04-root.cc : illustrates multi-jet rates at LEP, using FastJet and runtime ROOT displays. Also shows how to save ROOT histograms in a file that can be opened in ROOT later. - vincia05-root.cc : illustrates b-fragmentation at LEP, using FASTJET and runtime ROOT displays. Also shows how to save and overplot results from previous runs. - vincia06.cc : boosted Higgs decays at LHC, with VINCIA doing the H->bb shower and PYTHIA doing the rest. - vincia08-root.cc : illustrates subleading-log sensitive variables, and shows how to run and plot several PYTHIA/VINCIA instances concurrently. - vincia10-root.cc : run several centre-of-mass energies sequentially, and plot how various quantities scale with energy. - vincia11.cc : output from VINCIA to HepMC ===== HADRON COLLIDER EXAMPLE PROGRAMS ========================================= - vincia21.cc : gg2gg - vincia22.cc : HardQCD:all - vincia23-root.cc : Drell-Yan, with example of bias applied to populate tail of Z pT distribution (with Z->neutrinos to focus on jets) - vincia24.cc : Drell-Yan, generating multiple HepMC files for uncertainty bands and how to use the weights to get the modified cross section. - vincia25.cc : Les Houches Events, W production ================================================================================ The examples can be compiled by make vinciaNN or make vinciaNN-root If you create a modified version, you can compile this using the existing Makefile as well. E.g., if you create a modified version of vincia01.cc and save it as vincia01mod.cc, compile it using: make vincia01mod If you name it vincia01mod-root.cc and use make vincia01mod-root, Vincia will automatically try to link to ROOT for you. See the Makefile and/or the HTML User Reference for what to do if this fails on your system. ---------------------------------------------------------------------------- VINCIA update notes: Note: see version 1.x update notes for changes prior to version 2.0.00 2.0.00 : March 2016 - Nadine Fischer joins as co-author. - First version for pp, ie including initial-state showers. - Significant modifications to file structure and class names, consolidating old FSR structure with new ISR components. - Moved "using namespace" statements inside Vincia namespace to protect downstream programs from unknowingly using the std and Pythia8 namespaces when including Vincia headers, following an analogous change in Pythia 8 itself. - Several new sets of MG4 matrix elements, for Drell-Yan, Higgs, and QCD processes at hadron colliders. Some existing MG4 matrix elements (for Z, H and W decays) have been rederived, using the updated convert.sh script, which allows to pass more general colour information. They also include the interference - Helicity dependence, sector shower, NLO corrections and massive partons are currently not available in the new code. A simplified set of mass-dependent corrections are still applied, including phase-space constraints and approximate universal suppression factors in the radiation patterns, but all 4-momenta are bookkept as being massless. - Updated VinciaRoot interface. 2.0.01 : April 2016 - Bug fixes to the setting of unordering and restarting scales. This mandated a revision to the default tune, so the parameters in the corresponding tune file share/Vincia/tunes/default.cmnd are different with respect to those of the preceding version. - Updated configure and Makefile structure to permit linking to root6. Many thanks to G. Borges for help with resolving the linking issues. Specifically, the relevant flags (eg --std=c++11) are now extracted from the appropriate root-config script, and it is ensured that the linker sees the ROOT include directories first. - Corrected a bug in VinClu::map2to3 (in Tools.cc) affecting the massive generalisation of the Kosower kinematics map. Thanks to Rob Verheyen for alerting us to this bug. - Included new ColourReconnection-sensitive observables measured by ALEPH in Z->3jets. Sensititivy appears to be limited though, albeit their paper demonstrates that extreme (unrealistic?) scenarios can be ruled out. The vincia04-root.cc example program was updated to include a calculation of the two data points from the paper that were corrected to the MC level. 2.2.00 : August 2017 - New helicity-dependent antenna functions for both ISR and FSR. Note that nonsingular terms of FSR antennae have been modified relative to the helictity-summed counterparts in previous versions. New forms documented in the Author's compendium and in upcoming paper. - New VINCIA initialisation structure, using vincia.init() instead of pythia.init(). Code example: // Create PYTHIA 8 instance Pythia pythia; // Create a VINCIA instance, plugged into the PYTHIA one. VinciaPlugin vincia(&pythia); // Use pythia.readFile() and pythia.readString() to modify settings // for both PYTHIA and VINCIA pythia.readFile("mySettings.cmnd"); // Initialise. (Automatically calls pythia.init() as well.) vincia.init(); - Automated Uncertainty-band variations reimplemented to follow similar structure as those in Pythia 8, based on user-definable labels and keywords. - Significant code simplifications. - Removed options to set user-defined finite terms. Similarly to PYTHIA the intention is that nonsingular-term variations will now only be performed in the context of the automated shower-uncertainty bands. - Consolidated the AntennaFunctions and AntennaSets .cc and .h files into one set, Antennae.cc and Antennae.h - Removed all references to the Ariadne factor since this was anyway only being used for Z decays and hence was really just a specialised matrix-element-like correction. - Removed the sector-shower option (was anyway only used for FF antennae). - Removed option to switch the collinear terms on/off. (Could be reinstated in future if need be, checking that consistent eikonal approximation(s) is obtained by the truncated functions.) - Removed explicit on/off flags for each antenna type since same functionality can be achieved by setting the corresponding chargeFactor = 0. - CMW rescaling carried out as global change on alphaS rather than as explicit rescaling of eikonal terms. - The intention is also to revert to an ordinary format of strongly ordered showers with MECs by default only two orders beyond Born so that they can be reached by the 2->4 showers. In principle, several VINCIA samples can then be combined, as usual, where each starts from a different multiplicity but a single SCALUP scale. Matrix elements for Born + n will therefore still be needed for n as high as possible. 2.2.01 : October 2017 - Compatibility with Pythia 8.230: removed calls to fsrShower.initPtr() and isrShower.initPtr since the method is not virtual in base class and a call to it will be issued during Pythia::init(). - Bug fix in configure script for --with-gzip option. - Changed default setting so helicityShowers are on. - Renamed nVariations() methods to nWeights(). - Deprecated --with-root5 flag since VinciaRoot now uses transparency methods which are only available in ROOT 6. - VinciaRoot: fixed bug affecting plotting of relative uncertainties. - Minor update of data comparison file share/Vincia/data/LEP-91-beauty.dat Z->4b branching fraction updated to current PDG value (1% change). 2.2.02 : December 2017 - Added functionality to bias all or g->bb or g->cc antenna functions by simple multiplicative factors, to enhance multijet and b/c events. Based on formalism in arXiv:1605.08352. Option for bias factors < 1 also implemented, with slightly different formalism (see compendium) so that it remains positive definite. - Implemented "antenna on the back" for 1/NC^2 terms as new default option for QG antenna functions. So far only for FF antenna functions. - Small updates to default tune parameters in view of new 1/NC^2 treatment. - Updated vincia03-Mesons and vincia03-Baryons plots and normalised rates to be per (charged) particle, so eg the rate shown for pi^+/- is 0.5 (pi+ + pi-). This highlights the degree to which pi+/- rates are the same as for pi0 (pi0 is slightly higher due to feed-down), and similarly for rho+- / rho0, and Sigma+- / Sigma0. - Updated vincia.weight() and related methods to simply wrap Pythia's Info: methods when Vincia = off. (So that a Vincia example program can still be used for pure Pythia.) - Reorganised HTML manual (and XML file set) collecting FSR and ISR shower parameters together on a single page. 2.2.04 : December 2018 - Minor update for compatibility with Pythia 8.240: - New base class structure for shower plugins. - PartonSystems for resonance decays now includes an entry for the decaying resonance. - Switched off use of MHV amplitudes by default (due to singularities for back-to-back incoming particles; to be deprecated in future versions). 2.2.05 : July 2019 - Bug fix for back-to-back particles in MHV amplitudes. MHV amplitudes switched back on by default. 2.3.00 : April 2019 - Internal use tag for benchmarking purposes only. No public release. 2.3.01 : September 2019 - Vincia 2.3 includes a new algorithm for coherent QED evolution, based on R. Kleiss and R. Verheyen, JHEP 1711 (2017) 182. - Mass corrections from Vincia 1 have been fully reinstated, as described in A. Gehrmann-de Ridder, M. Ritzmann, P. Skands, PRD85 (2012) 014013. The massive antenna functions have also been decomposed into separate helicity (chirality) contributions, which are used when the helicity-dependent shower mode is switched on. - New antenna-based implementation of showers in decays of (coloured) resonances, by H. Brooks. So far mainly tested for top decays. - Significant restructuring of code files and class structures, partly driven by ongoing work to merge Vincia into upcoming Pythia 8.3 release and partly by desire to clean up and simplify overall code structure. - Corrected a long-standing bug in the massive kinematics map for 2->3 FF branchings. - Matrix-Element corrections disabled. (Intended to be temporary, pending further code updates.) A new interface to MadGraph 5 is under development. - Removed all code related to ME merging, this also pending updates that will go into the Pythia 8.3 version of VINCIA. - Removed all Fortran dependencies. - Updated the Vincia svn repository to new HepForge Phabricator structure. 2.3.02 : December 2019 - Minor bug fixes to address compiler warnings.