HelacOnia Processes
 
 
HelacOnia [Sha15] is an external package which provides 
automated calculations for heavy quarkonia production using NRQCD, 
similar in style to MadGraph5 
and the extension MadOnia, which is only available for MadGraph4. This 
can be useful when additional quarkonia processes other than the 
internal processes provided in Onia 
are needed, including matrix elements which are not spin-averaged, as 
well as the ability to produce n-leg matrix elements beyond 
the leading tree-level diagrams. The HelacOnia code can be downloaded 
from 
 
  http://helac-phegas.web.cern.ch/helac-phegas/helac-onia.html, 
where only version 2 and above is compatible with PYTHIA. 
 
 
Within HelacOnia, events can automatically be passed to PYTHIA for 
additional processing, e.g. showering, MPI, and 
hadronization. However, in many cases it may be simpler to produce 
HelacOnia events directly in PYTHIA. The LHAupHelaconia 
class provided in Pythia8Plugins/LHAHelaconia is designed 
to provide such utility. Here we will describe how this can be used to 
wrap the HelacOnia generator as a PYTHIA Les Houches interface. 
 
 
Of course, HelacOnia can also output files of parton-level events 
according to the LHEF standard, 
that can be read in and processed further by PYTHIA 8. This is the 
most commonly used approach, and requires no further description here. 
 
 
HelacOnia executable inside PYTHIA
 
 
The Pythia::setLHAupPtr(LHAup* lhaUpPtr) method allows 
a Pythia generator to accept a pointer to an object derived from the 
LHAup base class. 
Such an object will be initialized from within Pythia, and be called 
repeatedly to generate the next parton-level event, using the LHA 
specification as a standard to transfer the relevant information back 
to Pythia. Properly constructed, the operation of an LHAup 
object thus is almost completely hidden from the user, and generates 
events almost like an ordinary internal Pythia process. 
 
 
The LHAupHelaconia is precisely such a class, derived from 
LHAup, that contains the code needed to wrap a 
HelacOnia executable. Thereby the generation of HelacOnia 
processes from within Pythia becomes straightforward. An explicit 
example is provided in main363.cc. We describe some of the 
key elements used there and in the general case. 
 
 LHAupHelaconia::LHAupHelaconia(Pythia* pythia, string dir = "helaconiarun", string exe = "ho_cluster")   
creates an instance of the LHAupHelaconia class. 
argument pythia   :  pointer to the Pythia instance, 
such that some of its facilities can be used inside the interface. 
   
argument dir  (default = helaconiarun) :  the name of the run 
directory, into which HelacOnia puts its (intermediate) results. 
   
argument exe  (default = ho_cluster) :  the name of the HelacOnia 
executable that LHAupHelaconia is meant to wrap. In addition 
it may be necessary to prepend the full pathname of the executable: 
"(something)/HELAC-Onia-2.0.1/cluster/bin/ho_cluster". 
   
   
 
 bool LHAupHelaconia::readString(string line)   
allows the user to send commands to HelacOnia. 
argument line   :  the command to be sent to HelacOnia. For 
example, the following will produce J/psi events events from 13 TeV 
proton proton collisions: 
readString("generate u u~ > 
cc~(3S11) g"); 
 A special case is the generation of 
colour-octet states. In PYTHIA these are evolved to colour-singlet 
states through the emission of a soft gluon with the mass splitting 
set by Onia:massSplit. To ensure the colour-octet states 
in HelacOnia are produced with the correct masses needed for this 
splitting, the specific colour-octet state for the process must be 
set. For example: 
readString("generate u u~ > cc~(3S18) g"); 
requires that the colour-singlet state into which the 
colour-octet state should decay be set. This could be set via: 
readString("set state = 443"); 
for the case where a final state J/psi is 
requested. Note that this is not a command passed to HelacOnia, but 
rather a command which PYTHIA uses to set the heavy quark mass in 
HelacOnia and then translate the HelacOnia output to the correct 
colour-singlet state. 
   
   
 
 void LHAupHelaconia::setEvents(int events)   
the number of events to generate per HelacOnia run. Normally does not 
need to be set, but defaults to 10000. 
   
 
 void LHAupHelaconia::setSeed(int seed, int runs = 30081)   
the random seed (sequence), normally not needed to be set explicitly. 
If the random seed is negative (default of -1), then the HelacOnia 
seed is taken as the Pythia parameter "Random:seed", which 
must be greater than 0. If the maximum number of allowed runs is exceeded 
(default of 30081) an error is thrown. The seed for a HelacOnia run is set as: 
 (random seed - 1) * (maximum runs) + (number of runs) + 1. 
HelacOnia can only handle random seeds up to 30081 * 30081. So, with 
this strategy, one can generate Pythia jobs with seeds from 1 to 30081, 
with each job running HelacOnia less than 30081 times, and ensure a fully 
statistically independent sample. If more than 30081 jobs are needed, then 
the maximum allowed runs can be lowered accordingly, and if need be, 
setEvents can be used to increase the number of events generated per run.