Currently the beam particles must be either a hadron pair, a lepton
pair, a photon pair, a lepton and a hadron or a photon and a hadron.
In the first category *p p* and *pbar p*
combinations dominate, but it is also possible to combine with
*pi^+*, *pi^-* and *pi^0*. In the second
*e^+ e^-* and *mu^+ mu^-* would be the most useful
combinations, but also others should work if combined with an
appropriate hard process.

`mode `

** Beams:idA **
(`default = `

)**2212**

The PDG `id`

code for the first incoming particle.
Allowed codes include
*2212 = p*, *-2212 = pbar*,
*2112 = n*, *-2112 = nbar*,
*211 = pi^+*, *-211 = pi^-*, *111 = pi^0*,
*990 = Pomeron* (used in diffractive machinery;
here mainly for debug purposes),
*22 = gamma* (for *gamma-gamma* and *gamma-hadron*
interactions, more info here),
*11 = e^-*, *-11 = e^+*,
*13 = mu^-*, *-13 = mu^+*,

and a few more leptons/neutrinos in a few combinations.

Recently heavy-ion collisions have
been implemented in PYTHIA. Therefore a handful of nuclei have been
added as allowed incoming beams, using PDG codes of the format
`100ZZZAAAI`

:
1000020040 = ^{4}He , 1000030060 = ^{6}Li,
1000060120 = ^{12}C, 1000080160 = ^{16}O,
1000290630 = ^{63}Cu, 1000791970 = ^{197}Au, and
1000822080 = ^{208}Pb. More can be added using the function
`ParticleData::addParticle`

.

`mode `

** Beams:idB **
(`default = `

)**2212**

The PDG `id`

code for the second incoming particle.

`mode `

** Beams:frameType **
(`default = `

; **1**`minimum = 1`

; `maximum = 5`

)

Choice of frame for the two colliding particles. For options
1 - 3 the beam identities are specified above, while they are
obtained by the Les Houches information for options 4 and 5.
`option `

** 1** : the beams are colliding in their CM frame,
and therefore only the CM energy needs to be provided, see
`Beams:eCM`

below.
`option `

** 2** : the beams are back-to-back, but with different energies,
see `Beams:eA`

and `Beams:eB`

below.
This option could also be used for fixed-target configurations.
`option `

** 3** : the beams are not back-to-back, and therefore the
three-momentum of each incoming particle needs to be specified, see
`Beams:pxA`

through `Beams:pzB`

below.
`option `

** 4** : the beam and event information is stored in a
Les Houches Event File,
see `Beams:LHEF`

below.
`option `

** 5** : the beam and event information is obtained by a
pointer to an `LHAup`

class instance.

`parm `

** Beams:eCM **
(`default = `

; **14000.**`minimum = 0.`

)

Collision CM energy, to be set if `Beams:frameType`

= 1.

`parm `

** Beams:eA **
(`default = `

; **7000.**`minimum = 0.`

)

The energy of the first incoming particle, moving in the
*+z *direction, to be set if `Beams:frameType`

= 2.
If the particle energy is smaller than its mass
it is assumed to be at rest.

`parm `

** Beams:eB **
(`default = `

; **7000.**`minimum = 0.`

)

The energy of the second incoming particle, moving in the
*-z* direction, to be set if `Beams:frameType`

= 2.
If the particle energy is smaller than its mass
it is assumed to be at rest.

`parm `

** Beams:pxA **
(`default = `

)**0.**

The *p_x* component of the first incoming particle,
to be set if `Beams:frameType`

= 3.

`parm `

** Beams:pyA **
(`default = `

)**0.**

The *p_y* component of the first incoming particle,
to be set if `Beams:frameType`

= 3.

`parm `

** Beams:pzA **
(`default = `

)**7000.**

The *p_z* component of the first incoming particle,
to be set if `Beams:frameType`

= 3.

`parm `

** Beams:pxB **
(`default = `

)**0.**

The *p_x* component of the second incoming particle,
to be set if `Beams:frameType`

= 3.

`parm `

** Beams:pyB **
(`default = `

)**0.**

The *p_y* component of the second incoming particle,
to be set if `Beams:frameType`

= 3.

`parm `

** Beams:pzB **
(`default = `

)**-7000.**

The *p_z* component of the second incoming particle,
to be set if `Beams:frameType`

= 3.

`word `

** Beams:LHEF **
(`default = `

)**void**

The name of a Les Houches Event File,
to be set if `Beams:frameType`

= 4.

`word `

** Beams:LHEFheader **
(`default = `

)**void**

As some information in a Les Houches Event File init block is only known
at the end of generation, some programs choose to output this as a
separate file. If `Beams:LHEFheader`

is given, information up
till the end of the init block is read from this file, with
the events themselves read as usual from the file given in
`Beams:LHEF`

.

`flag `

** Beams:newLHEFsameInit **
(`default = `

)**off**

Allow to begin reading events from a new LHEF or or a new
`LHAup`

instance without a completely new initialization.
Only useful when `Beams:frameType`

= 4 or 5.

`flag `

** Beams:readLHEFheaders **
(`default = `

)**on**

Read in LHEF header blocks and store them in the
Info class. See also
LHAupLHEF
and the Les Houches Event files
section for more information.

`mode `

** Beams:nSkipLHEFatInit **
(`default = `

)**0**

Skip the first *nSkip* events of the input stream
(cf. the `LHAup::skipEvent(nSkip)`

method).
Only used when `Beams:frameType`

= 4 or 5.

`flag `

** Beams:strictLHEFscale **
(`default = `

)**off**

Always use the `SCALUP`

value read from LHEF
as production scale for particles, also including particles
coming from resonance decays. By default, the production scale
of resonance decay products (W-, Z-, H-bosons, top quarks) will
be set to *M/2*, where *M* is the mass of the resonance.

`flag `

** Beams:setProductionScalesFromLHEF **
(`default = `

)**off**

If enabled, production scales for all particles in an input Les Houches
event will be set by using auxiliary information provided in the
input event. Depending on which LHEF version is used, different
information will be read. For LHEF 1.0, scale information can be
transferred by including a line starting with the hashtag
(#) character at the end of the event. The hashtag should be
followed by the sequential scale values of the particles with status 1.
For LHEF 3.0, the standardised *<scales>* tag is used
instead. In this case, please ensure that production scale of
the final state particle with position *i* in the input event
will be transferred as the value of a scales tag attribute which contains
*i* at the end of the attribute name, separated from the rest of
the name by an underscore (_). An example *<scales>* tag
would be *<scales muf="100" pt_start_3="100" pt_start_4="50">
</scales>*. This could be used to set the production scales
of particles three and four to 100 GeV and 50 GeV, respectively, provided
that these particles have status 1.

The core extension in this option is that the multiparticle interactions
(MPI) machinery is initialized over a (logarithmically spaced) grid of
collision energies, from the maximal energy provided at the
initialization down to a lower cutoff (see `eMinPert`

below).
For each new event, with a new CM energy, a suitable interpolation is
then performed among the generation coefficients determined at
initialization. The MPI framework is what is needed to simulate
hadronic nondiffractive events (`SoftQCD:nonDiffractive`

).
Pretty much the same strategy is already used for diffraction, to handle
MPIs inside the variable-mass diffractive systems. Thus all the
Soft QCD processes can be used
within this framework. Below the minimal energy for a perturbative
description (see below) instead the simplified
Low-energy QCD processes
can be used. It is not possible to generate other processes
with the variable-energy framework, however, and the program will abort
if you try.

The initialization involves setting up optimal coefficients for the kinematics selection in the subsequent MPI generation, and finding the associated maximum of the differentialcross section. At a fixed energy this typically takes less than a second, and so normally is not noticeable.It is a major fraction of the full PYTHIA initialization time, however. Thus the initialization over a grid of energies raises the total initialization time appreciable, to the order of ten seconds. Initialization of diffraction contributes comparable numbers, when switched on. You should therefore not be surprised that the startup time is longer than usual. The subsequent event generation should not become noticeably slower, however.

There are three main settings in this framework.

`flag `

** Beams:allowVariableEnergy **
(`default = `

)**off**

Master switch to allow collision energies below the initialization one,
as described above.

`parm `

** Beams:eMinPert **
(`default = `

; **10.**`minimum = 10.`

)

The lowest CM energy that collisions are allowed to have. The highest
is set by the full energy at initialization, as calculated in the
respective options above. If you do not want to generate events with
a higher collision energy than this you can save some initialization
time by raising this number accordingly, so that fewer grid energies need
to be used. You should not lower the value below the default one, however,
since the perturbative MPI machinery cannot be made to work at lower
energies. If you do want to generate events with lower energies, it
is possible in a nonperturbative framework, see next.

`parm `

** Beams:eWidthPert **
(`default = `

; **10.**`minimum = 1.`

)

A simpler low-mass description can be used for energies below the
threshold energy *e_min* = `eMinPert`

above, with
only longitudinally stretched strings. A gradual switch-over between
the simple low-energy and perturbative high-energy regimes is then
natural. The probability for the latter picture is parametrized as
*
P_pert = 1 - exp( (e_CM - e_min) / e_width )
*

which vanishes for the CM energy *e_CM < e_min*, and is
*1 - 1/e = 0.632* for *e_CM = e_min + e_width*.
The current parameter is this *e_width.*

To input the variable energy, the normal argument-less
`Pythia::next()`

method has three siblings that take
relevent arguments as required by the `Beams:frameType`

.

** bool Pythia::next(double eCM) **

events created by the collision of two particles coming in along the
*+-z* axis in their common rest frame, with the CM energy as
argument, to be used for `Beams:frameType = 1`

.

** bool Pythia::next(double eA, double eB) **

events created by the collision of two particles coming in along the
*+-z* axis, with the respective energies as arguments, to be
used for `Beams:frameType = 2`

.

** bool Pythia::next(double pxA, double pyA, double pzA, double pxB, double pyB, double pzB) **

events created by two incoming particles with arbitrary three-momenta,
to be used for `Beams:frameType = 3`

.

On this page you can set the momentum spread according to a simple
Gaussian distribution. If you instead want a more sophisticated
parametrization, you can write and link your own
`BeamShape`

class.

`flag `

** Beams:allowMomentumSpread **
(`default = `

)**off**

Allow the beam momenta to be smeared around their initialization
nominal values.

`parm `

** Beams:sigmaPxA **
(`default = `

; **0.**`minimum = 0.`

)

The width of a Gaussian distribution of the *p_x* spread of the
first incoming particle.

`parm `

** Beams:sigmaPyA **
(`default = `

; **0.**`minimum = 0.`

)

The width of a Gaussian distribution of the *p_y* spread of the
first incoming particle.

`parm `

** Beams:sigmaPzA **
(`default = `

; **0.**`minimum = 0.`

)

The width of a Gaussian distribution of the *p_z* spread of the
first incoming particle.

`parm `

** Beams:maxDevA **
(`default = `

; **5.**`minimum = 0.`

)

The triply Gaussian distribution *(p_x, p_y, p_z)* is restricted to
a maximal total deviation from the nominal values *(p_x0, p_y0, p_z0)*
for the first incoming particle, like
*
(p_x - p_x0)^2/sigma_px^2 + (p_y - p_y0)^2/sigma_py^2 +
(p_z - p_z0)^2/sigma_pz^2 < maxDev^2
*

(Note the absence of a factor 2 in the denominator, unlike the Gaussians
used to pick *(p_x, p_y, p_z)*.)

`parm `

** Beams:sigmaPxB **
(`default = `

; **0.**`minimum = 0.`

)

The width of a Gaussian distribution of the *p_x* spread of the
second incoming particle.

`parm `

** Beams:sigmaPyB **
(`default = `

; **0.**`minimum = 0.`

)

The width of a Gaussian distribution of the *p_y* spread of the
second incoming particle.

`parm `

** Beams:sigmaPzB **
(`default = `

; **0.**`minimum = 0.`

)

The width of a Gaussian distribution of the *p_z* spread of the
second incoming particle.

`parm `

** Beams:maxDevB **
(`default = `

; **5.**`minimum = 0.`

)

The triply Gaussian distribution *(p_x, p_y, p_z)* is restricted to
a maximal total deviation from the nominal values *(p_x0, p_y0, p_z0)*,
for the second incoming particle, like
*
(p_x - p_x0)^2/sigma_px^2 + (p_y - p_y0)^2/sigma_py^2 +
(p_z - p_z0)^2/sigma_pz^2 < maxDev^2
*

(Note the absence of a factor 2 in the denominator, unlike the Gaussians
used to pick *(p_x, p_y, p_z)*.)

`BeamShape`

class.
`flag `

** Beams:allowVertexSpread **
(`default = `

)**off**

Allow the interaction vertex of the two colliding beams to be smeared.
If off, then the vertex is set to be the origin.

`parm `

** Beams:sigmaVertexX **
(`default = `

; **0.**`minimum = 0.`

)

The width of a Gaussian distribution of the *x* location of the
interaction vertex.

`parm `

** Beams:sigmaVertexY **
(`default = `

; **0.**`minimum = 0.`

)

The width of a Gaussian distribution of the *y* location of the
interaction vertex.

`parm `

** Beams:sigmaVertexZ **
(`default = `

; **0.**`minimum = 0.`

)

The width of a Gaussian distribution of the *z* location of the
interaction vertex.

`parm `

** Beams:maxDevVertex **
(`default = `

; **5.**`minimum = 0.`

)

The triply Gaussian distribution of interaction vertex position
*(x, y, z)* is restricted to a maximal total deviation from the
origin, like
*
x^2/sigma_x^2 + y^2/sigma_y^2 + z^2/sigma_z^2 < maxDevVertex^2
*

(Note the absence of a factor 2 in the denominator, unlike the Gaussians
used to pick *(x, y, z)*.)

`parm `

** Beams:sigmaTime **
(`default = `

; **0.**`minimum = 0.`

)

The width of a Gaussian distribution of the collision time (in units of
mm/c). Note that, if the above space parametrization is viewed as the
effect of two incoming beams along the *+-z* axis, with each beam
having a Gaussian spread, then the spread of the time would also become
a Gaussian with the same width as the *z* one (times the
velocity of the beams, which we expect is close to unity). For flexibility
we have not enforced any such relation, however.

`parm `

** Beams:maxDevTime **
(`default = `

; **5.**`minimum = 0.`

)

The collision time is restricted to be in the range
*|t| < sigma_t * maxDevTime*.

The distributions above are all centered at the origin. It is also
possible to shift the above distributions to be centered around another
nominal position. You must have `Beams:allowVertexSpread = on`

to use this possibility.

`parm `

** Beams:offsetVertexX **
(`default = `

)**0.**

The *x* location of the interaction vertex is centered at this value.

`parm `

** Beams:offsetVertexY **
(`default = `

)**0.**

The *y* location of the interaction vertex is centered at this value.

`parm `

** Beams:offsetVertexZ **
(`default = `

)**0.**

The *z* location of the interaction vertex is centered at this value.

`parm `

** Beams:offsetTime **
(`default = `

)**0.**

The time *t* of the interaction vertex is centered at this value.