1. Fragmentation functions
  2. Fragmentation pT
  3. Jet joining procedure
  4. Colour tracing
  5. Simplifying systems
  6. Ministrings
  7. Junction treatment
Fragmentation in PYTHIA is based on the Lund string model [And83, Sjo84]. Several different aspects are involved in the physics description, which here therefore is split accordingly. This also, at least partly, reflect the set of classes involved in the fragmentation machinery.

The variables collected here have a very wide span of usefulness. Some would be central in any hadronization tuning exercise, others should not be touched except by experts.

The fragmentation flavour-choice machinery is also used in a few other places of the program, notably particle decays, and is thus described on the separate Flavour Selection page.

Several methods are in place to allow the user to reweight generated events in the parameters of the fragmentation model. This allows the user to perform fast parameter variation or oversample rare configurations, and reweight to the correct cross section. These methods are documented on the separate Hadronization Variations page.

Note that the fragmentation in a Hidden Valley scenario is modelled in a similar spirit as for ordinary string fragmentation, but with a separate set of parameters. Relevant parameters for it are closely related to the scenario chosen, and therefore are documented on the same page.

Fragmentation functions

The StringZ class handles the choice of longitudinal lightcone fraction z according to one of two possible shape sets.

The Lund symmetric fragmentation function [And83] is the only alternative for light quarks. It is of the form
f(z) = (1/z) * (1-z)^a * exp(-b m_T^2 / z)
with the two main free parameters a and b to be tuned to data. They are stored in

parm  StringZ:aLund   (default = 0.68; minimum = 0.0; maximum = 2.0)
The a parameter of the Lund symmetric fragmentation function.

parm  StringZ:bLund   (default = 0.98; minimum = 0.2; maximum = 2.0)
The b parameter of the Lund symmetric fragmentation function.

In the context of fits to experimental data, note that the a and b parameters typically exhibit a very high degree of correlation. An option for choosing an alternative parameterisation is therefore provided, whereby the user specifies the desired average value of the fragmentation function for primary rho mesons instead of the b parameter. The a parameter should still be given by StringZ:aLund as usual. The rho has been chosen as reference since its mass is near the average of the primary hadron production, while pions come to dominate only after secondary decays. This option can be enabled via the following flag:

flag  StringZ:deriveBLund   (default = off)
When set to on, the b parameter is treated as a derived quantity; i.e., the value of StringZ:bLund is ignored in favour of the StringZ:avgZLund parameter below. (The StringZ:bLund parameter is then also reset to the derived value so that it can be queried after initialisation, if desired.)

parm  StringZ:avgZLund   (default = 0.55; minimum = 0.30; maximum = 0.70)
When StringZ:deriveBLund is set to on, this parameter specifies the average of the fragmentation function for primary rho mesons, evaluated at mT^2 = mRho^2 + 2StringPT:sigma^2. The appropriate b-parameter value is computed automatically during initialisation and the StringZ:bLund parameter is updated accordingly. Note that the derived value is allowed to exceed the nominal limits given for bLund above. This is intended to allow fits to see the functional behaviour even outside the nominal limits.

In principle, each flavour can have a different a. Then, for going from an old flavour i to a new j one the shape is
f(z) = (1/z) * z^{a_i} * ((1-z)/z)^{a_j} * exp(-b * m_T^2 / z)
This is only implemented for s quarks and diquarks relative to normal quarks:

parm  StringZ:aExtraSQuark   (default = 0.0; minimum = 0.0; maximum = 2.0)
allows a larger a for s quarks, with total a = aLund + aExtraSQuark.

parm  StringZ:aExtraDiquark   (default = 0.97; minimum = 0.0; maximum = 2.0)
allows a larger a for diquarks, with total a = aLund + aExtraDiquark.

Finally, the Bowler modification [Bow81] introduces an extra factor
1/z^{r_Q * b * m_Q^2}
for heavy quarks. To keep some flexibility, a multiplicative factor r_Q is introduced, which ought to be unity (provided that quark masses were uniquely defined) but can be set in

parm  StringZ:rFactC   (default = 1.32; minimum = 0.0; maximum = 2.0)
r_c, i.e. the above parameter for c quarks.

parm  StringZ:rFactB   (default = 0.855; minimum = 0.0; maximum = 2.0)
r_b, i.e. the above parameter for b quarks.

parm  StringZ:rFactH   (default = 1.0; minimum = 0.0; maximum = 2.0)
r_h, i.e. the above parameter for heavier hypothetical quarks, or in general any new coloured particle long-lived enough to hadronize.

Within the string framework, the b parameter is universal, i.e. common for all flavours. Nevertheless, for fits to experimental data, better agreement can be obtained if both a_Q and b_Q can be set freely in a general expression
f(z) = 1/z^{1 + r_Q * b_Q * m_Q^2} * (1-z)^a_Q * exp(-b_Q m_T^2 / z)
The below switches and values can be used to achieve this. They should be used with caution and constitute clear deviations from the Lund philosophy.

flag  StringZ:useNonstandardC   (default = off)
use the above nonstandard Lund ansatz for c quarks.

flag  StringZ:useNonstandardB   (default = off)
use the above nonstandard Lund ansatz for b quarks.

flag  StringZ:useNonstandardH   (default = off)
use the above nonstandard Lund ansatz for hypothetical heavier quarks.

parm  StringZ:aNonstandardC   (default = 0.3; minimum = 0.0; maximum = 2.0)
The a parameter in the nonstandard Lund ansatz for c quarks.

parm  StringZ:aNonstandardB   (default = 0.3; minimum = 0.0; maximum = 2.0)
The a parameter in the nonstandard Lund ansatz for b quarks.

parm  StringZ:aNonstandardH   (default = 0.3; minimum = 0.0; maximum = 2.0)
The a parameter in the nonstandard Lund ansatz for hypothetical heavier quarks.

parm  StringZ:bNonstandardC   (default = 0.8; minimum = 0.2; maximum = 2.0)
The b parameter in the nonstandard Lund ansatz for c quarks.

parm  StringZ:bNonstandardB   (default = 0.8; minimum = 0.2; maximum = 2.0)
The b parameter in the nonstandard Lund ansatz for b quarks.

parm  StringZ:bNonstandardH   (default = 0.8; minimum = 0.2; maximum = 2.0)
The b parameter in the nonstandard Lund ansatz for hypothetical heavier quarks.

As another nonstandard alternative, it is possible to switch over to the Peterson/SLAC formula [Pet83]
f(z) = 1 / ( z * (1 - 1/z - epsilon/(1-z))^2 )
for charm, bottom and heavier (defined as above) by the three flags

flag  StringZ:usePetersonC   (default = off)
use Peterson for c quarks.

flag  StringZ:usePetersonB   (default = off)
use Peterson for b quarks.

flag  StringZ:usePetersonH   (default = off)
use Peterson for hypothetical heavier quarks.

When switched on, the corresponding epsilon values are chosen to be

parm  StringZ:epsilonC   (default = 0.05; minimum = 0.01; maximum = 0.25)
epsilon_c, i.e. the above parameter for c quarks.

parm  StringZ:epsilonB   (default = 0.005; minimum = 0.001; maximum = 0.025)
epsilon_b, i.e. the above parameter for b quarks.

parm  StringZ:epsilonH   (default = 0.005; minimum = 0.0001; maximum = 0.25)
epsilon_h, i.e. the above parameter for hypothetical heavier quarks, normalized to the case where m_h = m_b. The actually used parameter is then epsilon = epsilon_h * (m_b^2 / m_h^2). This allows a sensible scaling to a particle with an unknown higher mass without the need for a user intervention.

Fragmentation pT

The StringPT class handles the choice of fragmentation pT. At each string breaking the quark and antiquark of the pair are supposed to receive opposite and compensating pT kicks. How they are distributed depends on the following flag:

flag  StringPT:thermalModel   (default = off)
If switched off the quark pT is generated according to the traditional Gaussion distribution in p_x and p_y separately. If switched on, the new "thermal model" [Fis16] is instead used, wherein the quark pT is generated such that the resulting hadron receives a pT according to an exponential distribution. Also the hadronic composition is affected, see further below.

Gaussian Distribution

For StringPT:thermalModel = off the quarks receive pT kicks according to a Gaussian distribution in p_x and p_y separately. Call sigma_q the width of the p_x and p_y distributions separately, i.e.
d(Prob) = exp( -(p_x^2 + p_y^2) / 2 sigma_q^2).
Then the total squared width is
<pT^2> = <p_x^2> + <p_y^2> = 2 sigma_q^2 = sigma^2.
It is this latter number that is stored in

parm  StringPT:sigma   (default = 0.335; minimum = 0.0; maximum = 1.0)
the width sigma in the fragmentation process.

Since a normal hadron receives pT contributions for two string breakings, it has a <p_x^2>_had = <p_y^2>_had = sigma^2, and thus <pT^2>_had = 2 sigma^2.

Some studies on isolated particles at LEP has indicated the need for a slightly enhanced rate in the high-pT tail of the above distribution. This would have to be reviewed in the context of a complete retune of parton showers and hadronization, but for the moment we stay with the current recipe, to boost the above pT by a factor enhancedWidth for a small fraction enhancedFraction of the breakups, where

parm  StringPT:enhancedFraction   (default = 0.01; minimum = 0.0; maximum = 1.)
enhancedFraction,the fraction of string breaks with enhanced width.

parm  StringPT:enhancedWidth   (default = 2.0; minimum = 1.0; maximum = 10.0)
enhancedWidth,the enhancement of the width in this fraction.

In the context of some toy studies [Fis16] the following three options have also been introduced, but are not part of any recommended framework.

parm  StringPT:widthPreStrange   (default = 1.0; minimum = 1.0; maximum = 10.0)
Prefactor multiplying the Gaussian width for strange quarks.

parm  StringPT:widthPreDiquark   (default = 1.0; minimum = 1.0; maximum = 10.0)
Prefactor multiplying the Gaussian width for diquarks. In case of diquarks with one or two strange quarks the prefactor is calculated by multiplying widthPreDiquark once or twice respectively with widthPreStrange.

flag  StringPT:mT2suppression   (default = off)
If switched on the flavour composition is chosen based on the hadronic transverse mass, mT^2_had, and not based on the quark masses. This implies a mass suppression factor exp(-m_had^2 / 2 sigma^2) .

Thermal Distribution

For StringPT:thermalModel = on the quark pT is generated such that the resulting hadron pT follows a thermal distribution
d(Prob) = exp( -pT_had/T) d^2pT_had
with temperature T, whose value is given by

parm  StringPT:temperature   (default = 0.21; minimum = 0.1; maximum = 0.5)
the temperature T in the fragmentation process.

parm  StringPT:tempPreFactor   (default = 1.21; minimum = 1.0; maximum = 1.5)
Temperature prefactor for strange quarks and diquarks. Default is determined to have the same average pT in u/d → s and s → u/d transistions.

Jet joining procedure

String fragmentation is carried out iteratively from both string ends inwards, which means that the two chains of hadrons have to be joined up somewhere in the middle of the event. This joining is described by parameters that in principle follows from the standard fragmentation parameters, but in a way too complicated to parametrize. The dependence is rather mild, however, so for a sensible range of variation the parameters in this section should not be touched.

parm  StringFragmentation:stopMass   (default = 1.0; minimum = 0.0; maximum = 2.0)
Is used to define a W_min = m_q1 + m_q2 + stopMass, where m_q1 and m_q2 are the masses of the two current endpoint quarks or diquarks.

parm  StringFragmentation:stopNewFlav   (default = 2.0; minimum = 0.0; maximum = 2.0)
Add to W_min an amount stopNewFlav * m_q_last, where q_last is the last q qbar pair produced between the final two hadrons.

parm  StringFragmentation:stopSmear   (default = 0.2; minimum = 0.0; maximum = 0.5)
The W_min above is then smeared uniformly in the range W_min_smeared = W_min * [ 1 - stopSmear, 1 + stopSmear ].

This W_min_smeared is then compared with the current remaining W_transverse to determine if there is energy left for further particle production. If not, i.e. if W_transverse < W_min_smeared, the final two particles are produced from what is currently left, if possible. (If not, the fragmentation process is started over.)

Colour tracing

flag  StringFragmentation:TraceColours   (default = off)
In some cases it is interesting to trace the primary hadrons back to the string pieces from which they were formed. If StringFragmentation:TraceColours is switched on, this is done by setting colour and anticolour indices for the primary hadrons to the indices of the string piece where the corresponding break-ups are assumed to have happened. To avoid the possible confusion of having colour indices on colour singlet particles, this flag is by default off.

Simplifying systems

There are a few situations when it is meaningful to simplify the original task, one way or another.

parm  HadronLevel:mStringMin   (default = 1.; minimum = 0.5; maximum = 1.5)
Decides whether a partonic system should be considered as a normal string or a ministring, the latter only producing one or two primary hadrons. The system mass should be above mStringMin plus the sum of quark/diquark constituent masses for a normal string description, else the ministring scenario is used.

parm  FragmentationSystems:mJoin   (default = 0.3; minimum = 0.2; maximum = 1.)
When two colour-connected partons are very nearby, with at least one being a gluon, they can be joined into one, to avoid technical problems of very small string regions. The requirement for joining is that the invariant mass of the pair is below mJoin, where a gluon only counts with half its momentum, i.e. with its contribution to the string region under consideration. (Note that, for technical reasons, the 0.2 GeV lower limit is de facto hardcoded.)

parm  FragmentationSystems:mJoinJunction   (default = 1.0; minimum = 0.5; maximum = 2.)
When the invariant mass of two of the quarks in a three-quark junction string system becomes too small, the system is simplified to a quark-diquark simple string. The requirement for this simplification is that the diquark mass, minus the two quark masses, falls below mJoinJunction. Gluons on the string between the junction and the respective quark, if any, are counted as part of the quark four-momentum. Those on the two combined legs are clustered with the diquark when it is formed.


The MiniStringFragmentation machinery is only used when a string system has so small invariant mass that normal string fragmentation is difficult/impossible. Instead one or two particles are produced, in the former case shuffling energy-momentum relative to another colour singlet system in the event, while preserving the invariant mass of that system. With one exception parameters are the same as defined for normal string fragmentation, to the extent that they are at all applicable in this case. A discussion of the relevant physics is found in [Nor00]. The current implementation does not completely abide to the scheme presented there, however, but has in part been simplified. (In part for greater clarity, in part since the class is not quite finished yet.)

mode  MiniStringFragmentation:nTry   (default = 2; minimum = 1; maximum = 10)
Whenever the machinery is called, first this many attempts are made to pick two hadrons that the system fragments to. If the hadrons are too massive the attempt will fail, but a new subsequent try could involve other flavour and hadrons and thus still succeed. After nTry attempts, instead an attempt is made to produce a single hadron from the system. Should also this fail, some further attempts at obtaining two hadrons will be made before eventually giving up.

flag  MiniStringFragmentation:tryAfterFailedFrag   (default = off)
If normal string fragmentation fails for a parton system, it is optionally possible to attempt to fragment it as if it had been a ministring (c.f. HadronLevel:mStringMin). This is mainly relevant for heavy-ion collisions and for the QCD-based colour-reconnection model, where many high-multiplicity events have a higher probability to have failed fragmentation (hence throwing the whole event away may skew the multiplicity distribution).

Junction treatment

A junction topology corresponds to an Y arrangement of strings i.e. where three string pieces have to be joined up in a junction. Such topologies can arise if several valence quarks are kicked out from a proton beam, or in baryon-number-violating SUSY decays. Special attention is necessary to handle the region just around the junction, where the baryon number topologically is located. The junction fragmentation scheme is described in [Sjo03] and [Alt24]. The parameters in this section should not be touched except by experts.

parm  StringFragmentation:pNormJunction   (default = 2.0; minimum = 0.5; maximum = 10)
Used to find the effective rest frame of the junction, which is complicated when the three string legs may contain additional gluons between the junction and the endpoint. Should in principle be (close to) sqrt((1 + a) / b), with a and b the parameters of the Lund symmetric fragmentation function.

parm  StringFragmentation:eBothLeftJunction   (default = 1.0; minimum = 0.5)
Retry (up to 10 times) when the first two considered strings in to a junction both have a remaining energy (in the junction rest frame) above this number.

parm  StringFragmentation:eMaxLeftJunction   (default = 10.0; minimum = 0.)
Retry (up to 10 times) when the first two considered strings in to a junction has a highest remaining energy (in the junction rest frame) above a random energy evenly distributed between eBothLeftJunction and eBothLeftJunction + eMaxLeftJunction (drawn anew for each test).

parm  StringFragmentation:eMinLeftJunction   (default = 0.2; minimum = 0.)
Retry (up to 10 times) when the invariant mass-squared of the final leg and the leftover momentum of the first two treated legs falls below eMinLeftJunction times the energy of the final leg (in the junction rest frame).

flag  StringFragmentation:pearlFragmentation   (default = off)
Optionally allow to use a gluon approximation for pearl-on-a-string junction topologies. Pearl-on-a-string is a junction topology such that the junction gets stuck to a soft endpoint parton. In these cases for light quarks, the propagation of the pT is similar to a soft gluon kink, and can be fragmented by approximating the pearl as a gluon.

parm  StringFragmentation:pearlProbFactor   (default = 4; minimum = 1)
The gluon approximation for pearl-on-a-string cases is chosen probabilistically. This parameter, f_pearl, modifies the probability distribution used and has the general form of
prob(x) = 1 / (1 + (4Δv)fpearl).
Here Δv, which varies between 0 and 1/2, is a measure of the total deceleration the pearl (ie the soft parton) experiences over a time characteristic of hadronization (here given by the pNormJunction parameter above).

flag  StringFragmentation:strangeJunctions   (default = off)
Switching this parameter on allows strangeness enhancement for string breaks next to a junction.

parm  StringFragmentation:strangeJuncFactor   (default = 0.5; minimum = 0.; maximum = 1.0)
This parameter, s_J, scales how much strangeness enhancement around a junction by modifying the probability StringFlav:probStoUD,
P'(s:u/d) = P(s:u/d)(1 - s_J).

parm  StringFragmentation:strangePearlFactor   (default = 0.5; minimum = 0.; maximum = 1.0)
Allow a different strangeness enhancement around a pearl junction.