## 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 the HelacOnia page, 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.