## Parton Vertex Information

While the setting of secondary production vertices of unstable hadrons and leptons is a standard part of the particle decay rotines, no corresponding standardized handling is in place for the evolution in the partonic or hadronization phases of the event generation. The intention is to provide such methods in due course.

There are some cases where such information is needed already now, specifically for the Rope Hadronization and the Hadronic Rescattering frameworks. Therefore the beginning of a framework is available, that can be used to set impact-parameter-plane vertices for partonic production by MPI, FSR, ISR and beam remnants. This is done in the `PartonVertex` class.

This is a base class, with a default implementation, but the user can replace it with a derived class that does a more sophisticated handling. Improvements and extensions are likely to come to the base class. So, while people are welcome to write their own derived classes, it is likely that these may need to be modified in later PYTHIA versions.

### Hadronization Parameters

Currently the base class implements a few alternative approaches to picking a partonic vertex, for use inside the rope hadronization and hadronic rescattering frameworks. There are also some free parameters in the models.

`flag` PartonVertex:setVertex (`default = off`)
Master switch to allow the setting of partonic vertices.

`mode` PartonVertex:modeVertex (`default = 2`; `minimum = 1`; `maximum = 4`)
Choice between alternative procedures to select vertex.
`option` 1 : Proton profile is a (Lorentz-contracted) uniform-parton-density ball. This gives an almond-shaped overlap region between two colliding hadrons, favouring MPI being displaced perpendicularly to the collision plane.
`option` 2 : Proton profile is a (Lorentz-contracted) three-dimensional Gaussian, or equivalently a two-dimensional one, since a Gaussian easily factorizes so that the z can be integrated out. This gives a Gaussian overlap region between the two colliding hadrons, since the product of two displaced Gaussians is another Gaussian.
`option` 3 : Proton profile is a Gaussian, as above, but elongated by a scale factor rEps in the x direction and compressed by the same factor in the y direction. Here rEps = sqrt( (1 + epsilon) / (1 - epsilon) ), where epsilon is described further below. If epsilon < 0 then the role of elongation and compression is exchanged.
`option` 4 : Proton profile is Gaussian, as above, but with a further modulation factor 1 + epsilon * cos(2 * phi), where the asymmetry parameter epsilon is described further below. The azimuthal angle phi is defined with respect the the hadron-hadron collision plane. Among rotationally symmetric parton distributions only the Gaussian one (or a sum of Gaussians) do not give rise to azimuthal asymmetries, so this option offers some further flexibility.
Warning: In the first option collisions cannot happen if the impact parameter is larger than twice the proton/hadron radius. The MPI machinery has a separate framework for selecting impact parameters, however, by default closer to option 2, and thus able to produce larger separations. To this end, the impact parameter is limited to be at most 0.95 of the maximal in option 1, and a warning is issued for values initially above that.

`parm` PartonVertex:phiAsym (`default = 0.`; `minimum = -0.9`; `maximum = 0.9`)
The azimuthal asymmetry parameter epsilon defined above for `PartonVertex:modeVertex =` 3 and 4. A positive (negative) value favours MPI production in (out of) the collision frame, as could be expected for a matter distribution with a flatter-(sharper-)than-Gaussian edge.

`parm` PartonVertex:ProtonRadius (`default = 0.85`; `minimum = 0.`; `maximum = 10.`)
The proton radius and shape depends on the collision energy and on the context in which it is used. The default value is based on the static charge-radius definition. If the DIPSY model [Fle11] is used, then for a description at LHC collision energies, say 14 TeV, the required profile corresponds roughly to a Gaussian with a width of around 0.7 fm.

`parm` PartonVertex:EmissionWidth (`default = 0.1`; `minimum = 0.`; `maximum = 10.`)
Vertices of ISR+FSR partons are smeared relative to their mother by a Gaussian distribution with a width of `EmissionWidth`/pT, where pT is the transverse momentum of the produced parton (in GeV). This parameter thus determined the overall strength of the transverse space smearing.

`parm` PartonVertex:pTmin (`default = 0.2`; `minimum = 0.05`; `maximum = 1.`)
The parton transverse smearing is assumed proportional to 1 / pT, but pT is limited to be above this parameter so as to avoid unreasonable values.

`flag` PartonVertex:randomPlane (`default = on`)
If off then the impact parameter vector lies in the xz plane, which is convenient for theoretical studies of azimuthal distributions. If on then the event will be rotated a random angle around the z axis so as to be more realistic. The angle can still be reconstructed from the vertices of the two incoming hadrons.

### External models

A derived class for setting parton vertex information can be provided to PYTHIA with the
`bool Pythia::setPartonVertexPtr( PartonVertex* partonVertexPtrIn)`
method. The methods in the derived `PartonVertex` class can then be used to add vertex information to produced particles, at creation time, in MPI, FSR and ISR and beam remnants. The assigned vertex information will afterwards be accessible as properties of the individual particles. Particles produced in other types of processes than the ones mentioned above will not have vertex information assigned (e.g. hard process), neither will particles produced in the weak shower.

virtual void init()
can be used to initialize various parameters of the model or precalculate common numbers. Note that a separate non-virtual method will already have provided pointers to the `Info`, `Settings` and `Rndm` classes, so that these are available in all derived classes.

virtual void vertexMPI( int iBeg, int nAdd, double bNow, Event& event)
Method to assign a production vertex to a particle produced in the MPI framework. Should set the vertices `vProd` of the particles concerned.
`argument` iBeg : is the index of the first parton of a MPI.
`argument` nAdd : is the number of partons involved in the MPI, currently always four: two in and two out.
`argument` bNow : is the impact parameter of the event. It is not expressed in physical units (like fm), but rescaled such that the average is unity for MPI events. See the section on Multiparton Interactions for a description of choices for the b dependence.
`argument` event : reference to the whole event, to read information from and set the relevant `vProd` values into.

virtual Vec4 vertexFSR( int iNow, Event& event)
Method to assign production vertex to a particle produced in the FSR (`TimeShower`). Should set the vertex `vProd` of the particle concerned.
`argument` iNow : is the index of the parton concerned. In a branching the daughters automatically inherit the vertex of the mother, if it has one, and similarly for the recoiler. This method is called specifically for what is considered the emitted parton of the process, i.e. the gluon in a q → q g branching, and allows the vertex of this parton to be modified.
`argument` event : reference to the whole event, to read information from and set the relevant `vProd` values into.

virtual Vec4 vertexISR( int iNow, Event& event)
Method to assign production vertex to a particle produced in the ISR (`SpaceShower`). Should set the vertices `vProd` of the particle concerned.
`argument` iNow : is the index of the parton concerned. This method is called three times for each ISR branching, for the daughter, the new recoiler and the sister.
`argument` event : reference to the whole event, to read information from and set the relevant `vProd` values into.

virtual void vertexBeam( int iBeam, vector<int>& iRemn, vector<int>& iInit, Event& event)
Method to assign production vertices for the beam itself and the beam remnants.
`argument` iBeam : is 0 and 1, respectively, for the two beams. The two beam particles are then located in event record positions 1 and 2, and normally you would set them to be displaced `+-bNow` along the x axis.
`argument` vector<int>& iRemn : are the indices of the beam remnants that could be displaced by you.
`argument` vector<int>& iInit : are the indices of the initiator partons for all the MPIs of the event. They already had their vertices assigned and should not be changed. But that information could be used e.g. to ensure that the energy-weighted average of all initiators and all remnants together give the proper beam impact parameter.
`argument` event : reference to the whole event, to read information from and set the relevant `vProd` values into.

virtual void vertexHadrons( int nBefFrag, Event& event)
Method to shift hadron production vertices by an amount related to that of the partons they come from. This may be the most complicated step of them all, since there is not a unique one-to-one association between a hadron and a parton.
`argument` nBefFrag : is the size of the event record before the latest fragmentation step, and `event.size()` the one after. All the hadrons in that range come from the fragmentation of the partons given by their common mother indices, and are open to receive modified production vertices.
`argument` event : reference to the whole event, to read information from and set the relevant `vProd` values into.