## Onia Showers

Measurements of onium isolation, see [LHC17], indicate that onium production cannot be sufficiently described by the hard processes of Onia Processes alone. Instead, the formation of onium states could occur later in the event at lower energy scales, described either through the formalism of fragmentation functions or parton showers. Consequently, the LETO project (named after the mother of the twins Apollo and Artemis) has implemented the production of onia within the simple Timelike Showers framework of PYTHIA. A full description of the LETO implementation can be found in [Coo23]. Production of any 1S0, 3S1, and 3PJ charmonium and bottomonium states via the colour-singlet and colour-octet mechanisms is available via the LETO parton shower. This includes by default, but is not limited to, production of the 1S0 eta states, the 3S1 J/psi and Upsilon and their radially excited states, as well as the 3PJ chi states.
Warning: matching between onium production from the hard processes and from LETO is not available, and consequently both LETO processes and onium hard processes should not be used at the same time as this will result in double counting. Indeed, it is expected that given a sufficiently complete set of splittings in LETO, hard process production should not be necessary. By default, hard process onium production is included in multi-parton interactions. If the onium shower is enabled, these onium processes are automatically no longer included in the multi-parton interactions.
Warning: due to the large number of splittings onium shower introduces, as well as current inefficiencies in the samplings for some of the splittings, the runtime for Pythia can increase significantly when onia showers are turned on; depending on what splittings are enabled as well as the beam configuration, the code can run up to five times slower.

Only the lowest-order colour-octet production mechanisms for these three spin configurations are provided via splittings into 3S1 colour-octet states. The gluon initiated splittings of this type are unusual in the context of a parton shower, as they are 1 → 1 processes, rather than the typical 1 → 2 processes. These splittings are treated as delta functions; if a gluon reaches the virtuality of an onium state, then such a colour-octet state may form. The result is to produce colour-octet states nearer to the end of the shower. Note that colour-octet states may also be produced in the splitting Q → (onium) Q where the colour-octet state is an unphysical 3S1 state that evolves to a 3PJ state [Yua94]. However, this process is sub-leading to the gluon initiated colour-octet process. For colour-singlet production ([Bra93], [Bra93a], [Bra94], [Bra95], and [Yua94]), both gluon and heavy-flavour quark initiated splittings are available. For the 3S1 colour-singlet state, the gluon initiated splitting is a 1 → 3 process, i.e. g → (onium) g g as required by the Landau-Yang theorem.

Whenever possible, the same notation and settings structure as Onia Processes is used. In principle, the same long-distance NRQCD matrix elements (LDMEs) that are used for the hard processes should also be used for the splittings of the LETO parton shower. However, for full flexibility, these LDMEs are specified independently for LETO and the hard processes. However, their default values are matched to those of the hard process LDMEs whenever possible. For consistency, all LDMEs are given in units of GeV^3. For the case of the 3PJ states, where the LDME units are typically GeV^5, the LDME provided to LETO should be divided by the squared mass of the heavy-flavour quark, <O[3P0(1)]>/m_Q^2. For the colour-octet states, the same particle ID convention as in Onia Processes is used, with the mass splitting between the colour-octet and physical colour-singlet states set by the `Onia:massSplit` parameter. Here, only the leading splittings into colour-octet 3S1(8) states are included, and so the notation is somewhat simpler than for the hard processes, where both 1S0(8) and 3PJ(8) processes are included for the physical colour-singlet 3S1(1) states.

### Radiation off octet onium states

In the current implementation, charmonium and bottomonium production can proceed either through colour-singlet or colour-octet mechanisms, either through 2 → 2 hard processes such as g g → (onium) g, or via splittings like g → (onium) g in the LETO parton shower. For colour-singlet production, the state does not radiate and the onium therefore is produced in isolation if produced from the hard process, up to normal underlying-event activity. If produced from the parton shower, the onium will be present within a jet, but will not radiate any further after being produced. For colour-octet states the situation is not so clear, but it is sensible to assume that such states can radiate further in the shower, assuming, of course, that the transverse momentum of the onium state is sufficiently high that radiation is of relevance. Consequently, colour-octet states produced either in the hard process or in the parton shower may be allowed to radiate further.

When an octet onium state radiates, there is a choice of splitting kernel for this process. The first and perhaps most natural choice is to assume the octet onium state radiates like a massive gluon, i.e. q → q g, while the second choice is to assume that the full radiation is provided by an incoherent sum of radiation off the quark and off the antiquark of the onium state. Thus the splitting kernel for this second option is taken to be the normal Q → Q g one, multiplied by a factor of two. Obviously this is a simplification of a more complex picture, averaging over factors pulling in different directions. Firstly, radiation off a gluon ought to be enhanced by a factor 9/4 relative to a quark rather than 2. Secondly, our use of the q → q g branching kernel is roughly equivalent to always following the harder gluon in a g → g g branching. This could give us a bias towards producing too hard onia. A soft gluon would have little phase space to branch into a heavy-quark pair however, so the bias may not be as big as it would seem at first glance.

Finally, note that the lower cutoff scale of the shower evolution depends on the onium mass rather than on the quark mass, as it should be. Gluons below the octet-onium scale should only be part of the octet-to-singlet transition.

`flag` OniaShower:all (`default = off`)
Common switch for the group of onia production.

`flag` OniaShower:all(1S0) (`default = off`)
Common switch for the group of 1S0 onia production, e.g. eta_c and eta_b.

`flag` OniaShower:all(3S1) (`default = off`)
Common switch for the group of 3S1 onia production, e.g. J/psi and Upsilon.

`flag` OniaShower:all(3PJ) (`default = off`)
Common switch for the group of 3PJ onia production, e.g. chi_c and chi_b.

`parm` OniaShower:ldmeFac (`default = 1.`; `minimum = 0.`)
Enhance all the onium LDMEs by a common factor. This is useful since onium production in the shower is relatively rare when using the default LDMEs. This allows one to conveniently increase the production rate without need to individually change each LDME. Note that increasing this factor to the point where there are multiple onia produced in the shower will result in unphysical results.

`mode` OniaShower:alphaScale (`default = 1`; `minimum = 0`; `maximum = 2`)
Choice of scale when evaluating the final alpha_s factor in the onia splitting functions. All other alpha_s factors are evaluated at the evolved p_T^2 of the dipole.
`option` 0 : the mass squared of the onia, m_O^2.
`option` 1 : the evolved p_T^2 of the dipole.
`option` 2 : the dipole centre-of-mass, s.

`mode` OniaShower:octetSplit (`default = 1`; `minimum = 0`; `maximum = 2`)
Choice of the splitting used for radiation from colour octet onium states.
`option` 0 : do not allow the octet states to radiate.
`option` 1 : treat the octet state like a massive gluon, g → g g.
`option` 2 : treat the octet state like a heavy-flavour quark, Q → Q g. The colour factor for this splitting can be modified by the following `octetColFac` parameter.

`parm` OniaShower:octetColFac (`default = 2.`; `minimum = 0.`; `maximum = 4.`)
The additional multiplicative colour factor used used in the q → q g splitting kernel for octet onium states (`OniaShower:octetSplit = 2`), normalized to the q → q g splitting kernel. Thus the default corresponds to twice the radiation off a quark. The physically preferred range would be between 1 and 9/4.

`flag` CharmoniumShower:all (`default = off`)
Common switch for the group of charmonium shower splittings, e.g. eta_c, J/psi and chi_c.

`flag` BottomoniumShower:all (`default = off`)
Common switch for the group of bottomonium production, e.g. eta_b, Upsilon and chi_b.

### Charmonium 1S0 States

Warning: changed `fvec`, `mvec` or `pvec` values must be provided as a comma-separated list with the right number of elements, without any blanks inside the list.

`mvec` CharmoniumShower:states(1S0) (`default = {441}`; `minimum = 0`)
The 1S0 charmonium states that can be produced in the shower. Note that all vectors within this section, either of flags or parameters, must be the same length as this vector.

`pvec` CharmoniumShower:O(1S0)[1S0(1)] (`default = {1.16}`; `minimum = 0.0`)
The colour-singlet long-distance matrix elements <O[1S0(1)]> for the 1S0 charmonium states. Units are GeV^3.

`pvec` CharmoniumShower:O(1S0)[3S1(8)] (`default = {0.0119}`; `minimum = 0.0`)
The colour-octet long-distance matrix elements <O[1S0(1)]> for the 1S0 charmonium states. Units are GeV^3.

`fvec` CharmoniumShower:c2ccbar(1S0)[1S0(1)]c (`default = {off}`)
Colour-singlet production of 1S0 charmonium states via the splitting c → ccbar[1S0(1)] c.

`fvec` CharmoniumShower:g2ccbar(1S0)[1S0(1)]g (`default = {off}`)
Colour-singlet production of 1S0 charmonium states via the splitting g → ccbar[1S0(1)] g.

`fvec` CharmoniumShower:g2ccbar(1S0)[3S1(8)] (`default = {off}`)
Colour-octet production of 1S0 charmonium states via the splitting g → ccbar[3S1(8)].

### Charmonium 3S1 States

`mvec` CharmoniumShower:states(3S1) (`default = {443,100443}`; `minimum = 0`)
The 3S1 charmonium states that can be produced in the shower. Note that all vectors within this section, either of flags or parameters, must be the same length as this vector.

`pvec` CharmoniumShower:O(3S1)[3S1(1)] (`default = {1.16,0.76}`; `minimum = 0.0`)
The colour-singlet long-distance matrix elements <O[3S1(1)]> for the 3S1 charmonium states. Units are GeV^3.

`pvec` CharmoniumShower:O(3S1)[3S1(8)] (`default = {0.0119,0.0050}`; `minimum = 0.0`)
The colour-octet long-distance matrix elements <O[3S1(8)]> for the 3S1 charmonium states. Units are GeV^3.

`fvec` CharmoniumShower:c2ccbar(3S1)[3S1(1)]c (`default = {off,off}`)
Colour-singlet production of 3S1 charmonium states via the splitting c → ccbar[3S1(1)] c.

`fvec` CharmoniumShower:g2ccbar(3S1)[3S1(1)]gg (`default = {off,off}`)
Colour-singlet production of 3S1 charmonium states via the splitting g → ccbar[3S1(1)] g g.

`fvec` CharmoniumShower:g2ccbar(3S1)[3S1(8)] (`default = {off,off}`)
Colour-octet production of 3S1 charmonium states via the splitting g → ccbar[3S1(8)].

### Charmonium 3PJ States

`mvec` CharmoniumShower:states(3PJ) (`default = {10441,20443,445}`; `minimum = 0`)
The 3PJ charmonium states that can be produced in the shower. Note that all vectors within this section, either of flags or parameters, must be the same length as this vector.

`pvec` CharmoniumShower:O(3PJ)[3P0(1)] (`default = {0.05,0.05,0.05}`; `minimum = 0.0`)
The color-singlet long-distance matrix elements <O[3P0(1)]>/m_Q^2 for the 3PJ charmonium states. The remaining <O[3PJ(1)]>/m_Q^2 are calculated from these long-distance matrix elements. Units are GeV^3.

`pvec` CharmoniumShower:O(3PJ)[3S1(8)] (`default = {0.0031,0.0031,0.0031}`; `minimum = 0.0`)
The color-octet long-distance matrix elements O[3S1(8)] for the 3PJ charmonium states.

`fvec` CharmoniumShower:c2ccbar(3PJ)[3PJ(1)]c (`default = {off,off,off}`)
Colour-singlet production of 3PJ charmonium states via the splitting c → ccbar[3PJ(1)] c.

`fvec` CharmoniumShower:c2ccbar(3PJ)[3S1(8)]c (`default = {off,off,off}`)
Colour-octet production of 3PJ charmonium states via the splitting c → ccbar[3S1(8)] c.

`fvec` CharmoniumShower:g2ccbar(3PJ)[3PJ(1)]g (`default = {off,off,off}`)
Colour-singlet production of 3PJ charmonium states via the splitting g → ccbar[3PJ(1)] g.

`fvec` CharmoniumShower:g2ccbar(3PJ)[3S1(8)] (`default = {off,off,off}`)
Colour-octet production of 3PJ charmonium states via the splitting g → ccbar[3S1(8)].

### Bottomonium 1S0 States

Warning: changed `fvec`, `mvec` or `pvec` values must be provided as a comma-separated list with the right number of elements, without any blanks inside the list.

`mvec` BottomoniumShower:states(1S0) (`default = {551}`; `minimum = 0`)
The 1S0 bottomonium states that can be produced in the shower. Note that all vectors within this section, either of flags or parameters, must be the same length as this vector.

`pvec` BottomoniumShower:O(1S0)[1S0(1)] (`default = {9.28}`; `minimum = 0.0`)
The colour-singlet long-distance matrix elements <O[1S0(1)]> for the 1S0 bottomonium states. Units are GeV^3.

`pvec` BottomoniumShower:O(1S0)[3S1(8)] (`default = {0.15}`; `minimum = 0.0`)
The colour-octet long-distance matrix elements <O[1S0(1)]> for the 1S0 bottomonium states. Units are GeV^3.

`fvec` BottomoniumShower:b2bbbar(1S0)[1S0(1)]b (`default = {off}`)
Colour-singlet production of 1S0 bottomonium states via the splitting b → bbbar[1S0(1)] c.

`fvec` BottomoniumShower:g2bbbar(1S0)[1S0(1)]g (`default = {off}`)
Colour-singlet production of 1S0 bottomonium states via the splitting g → bbbar[1S0(1)] g.

`fvec` BottomoniumShower:g2bbbar(1S0)[3S1(8)] (`default = {off}`)
Colour-octet production of 1S0 bottomonium states via the splitting g → bbbar[3S1(8)].

### Bottomonium 3S1 States

`mvec` BottomoniumShower:states(3S1) (`default = {553,100553,200553}`; `minimum = 0`)
The 3S1 bottomonium states that can be produced in the shower. Note that all vectors within this section, either of flags or parameters, must be the same length as this vector.

`pvec` BottomoniumShower:O(3S1)[3S1(1)] (`default = {9.28,4.63,3.54}`; `minimum = 0.0`)
The colour-singlet long-distance matrix elements <O[3S1(1)]> for the 3S1 bottomonium states. Units are GeV^3.

`pvec` BottomoniumShower:O(3S1)[3S1(8)] (`default = {0.15,0.045,0.075}`; `minimum = 0.0`)
The colour-octet long-distance matrix elements <O[3S1(8)]> for the 3S1 bottomonium states. Units are GeV^3.

`fvec` BottomoniumShower:b2bbbar(3S1)[3S1(1)]b (`default = {off,off,off}`)
Colour-singlet production of 3S1 bottomonium states via the splitting b → bbbar[3S1(1)] c.

`fvec` BottomoniumShower:g2bbbar(3S1)[3S1(1)]gg (`default = {off,off,off}`)
Colour-singlet production of 3S1 bottomonium states via the splitting g → bbbar[3S1(1)] g g.

`fvec` BottomoniumShower:g2bbbar(3S1)[3S1(8)] (`default = {off,off,off}`)
Colour-octet production of 3S1 bottomonium states via the splitting g → bbbar[3S1(8)].

### Bottomonium 3PJ States

`mvec` BottomoniumShower:states(3PJ) (`default = {10551,20553,555}`; `minimum = 0`)
The 3PJ bottomonium states that can be produced in the shower. Note that all vectors within this section, either of flags or parameters, must be the same length as this vector.

`pvec` BottomoniumShower:O(3PJ)[3P0(1)] (`default = {0.085,0.085,0.085}`; `minimum = 0.0`)
The color-singlet long-distance matrix elements <O[3P0(1)]>/m_Q^2 for the 3PJ bottomonium states. The remaining <O[3PJ(1)]>/m_Q^2 are calculated from these long-distance matrix elements. Units are GeV^3.

`pvec` BottomoniumShower:O(3PJ)[3S1(8)] (`default = {0.04,0.04,0.04}`; `minimum = 0.0`)
The color-octet long-distance matrix elements O[3S1(8)] for the 3PJ bottomonium states.

`fvec` BottomoniumShower:b2bbbar(3PJ)[3PJ(1)]b (`default = {off,off,off}`)
Colour-singlet production of 3PJ bottomonium states via the splitting b → bbbar[3PJ(1)] c.

`fvec` BottomoniumShower:b2bbbar(3PJ)[3S1(8)]b (`default = {off,off,off}`)
Colour-octet production of 3PJ bottomonium states via the splitting b → bbbar[3S1(8)] c.

`fvec` BottomoniumShower:g2bbbar(3PJ)[3PJ(1)]g (`default = {off,off,off}`)
Colour-singlet production of 3PJ bottomonium states via the splitting g → bbbar[3PJ(1)] g.

`fvec` BottomoniumShower:g2bbbar(3PJ)[3S1(8)] (`default = {off,off,off}`)
Colour-octet production of 3PJ bottomonium states via the splitting g → bbbar[3S1(8)].