## Heavy Ions

PYTHIA does not normally handle collisions involving heavy ions, but it includes a facility where a model for combining several nucleon-nucleon collisions into one heavy ion collision can be implemented. One such model, called Angantyr, is provided with PYTHIA and is inspired by the old Fritiof program from the Lund group [And86] with recent improvements [Bie16a] (see below).

To allow for the generation of collisions with heavy ions, PYTHIA includes a handful of nuclei with PDG numbers on the form 100ZZZAAAI: 4He (1000020040), 6Li (1000030060), 12C (1000060120), 16O (1000080160), 63Cu (1000290630), 129Xe (1000290630), 197Au (1000791970), and 208Pb(1000822080), but can be added using the function `ParticleData::addParticle`.

`mode` HeavyIon:mode (`default = 1`; `minimum = 1`; `maximum = 2`)
This is the master switch for heavy ions, and determines the mode of operation of the HeavyIon model.
`option` 1 : The heavy ion machinery will be used in case of ion beams.
`option` 2 : Even collisions without ions are treated using the heavy ion machinery. (Typically only used for debugging purposes.)

If `HeavyIon:mode` is on, the normal initialization in `Pythia::init()` is early on diverted to an object with the base class `HeavyIons` which may instantiate secondary `Pythia` objects needed to generate different types of nucleon-nucleon collisions that can be merged together into a full heavy ion event. This is all done in the virtual `HeavyIons::init()` function. Subsequent calls to `Pythia::next()` will then also be diverted to the virtual function `HeavyIons::next()` which will be responsible for building up the heavy ion collision. The final event will be available in the primary `Pythia` object.

`flag` HeavyIon:showInit (`default = on`)
Output detailed initialization information from the heavy ion model. Typically there will be several `Pythia` object initialised in a heavy ion run, this flag can be used to reduce the amount of output. If off, only the output from initialisation of the primary `Pythia` object will be shown

The `HeavyIon` class is very simple and flexible and basically only specifies that the `HeavyIons::init()` and `HeavyIons::next()` functions are overridden in a subclass. But there are a few additional helper classes that should be generic enough to be used by any model implemented.

- The `Nucleon` class represents a single nucleon in a nuclei. It can be a proton or a neutron (`id()`), it has a position in impact parameter space (`Vec2`), both absolute (`bPos()`) and relative to the nuclei (`nPos()`), and optionally it can be in a particular state represented by a vector of real numbers which are completely model dependent.
- The `SubCollision` class represents a potential nucleon-nucleon collision between a projectile and a target `Nucleon`.
- The `NucleusModel` class is a base class for implementing a model for the distribution in impact parameter space of nucleons in a nucleus. There are two ready-made subclasses called `WoodsSaxonModel`, implementing a standard Woods-Saxon distribution, and `GLISSANDOModel`, implementing the advanced model in [Bro09,Ryb14].

  `flag` HeavyIon:WSHardCore (`default = on`)
  In the default Woods-Saxon model for nucleon distributions, assume that there is a minimum distance between nucleons defined by a hard core radius in `HeavyIon:WSRh`.

  `parm` HeavyIon:WSRh (`default = 0.9`; `minimum = 0.0`)
  The hard core radius in units of fermi, defining the minimum distance between nucleons in a nucleus in the default Woods-Saxon model for nucleon distributions.

  `flag` HeavyIon:gaussHardCore (`default = off`)
  Option to use a Gaussian profile of the hard core instead of a sharp cut-off, inspired by [Bay95].

  `parm` HeavyIon:WSR (`default = 0.0`; `minimum = 0.0`)
  The radius of a nucleon in units of fermi in the default Woods-Saxon model for nucleon distributions. If zero, the size is given by the formulae [Ryb14], based on the number of nucleons in the nuclei and whether a hard core is used or not.

  `parm` HeavyIon:WSa (`default = 0.0`; `minimum = 0.0`)
  The skin width of a nucleus in units of fermi in the default Woods-Saxon model for nucleon distributions. If zero, the size is given by the numbers in [Ryb14], based on the number of nucleons in the nuclus and whether a hard core is used or not.
- The `ImpactParameterGenerator` is used to sample the impact parameter space for the colliding nuclei. The base class implements a Gaussian sampling, which means that the events produced will always be weighted. Other distributions can be implemented in subclasses.

  `parm` HeavyIon:bWidth (`default = 0.0`; `minimum = 0.0`)
  The width in fermi of the distribution by which the impact parameter is sampled. If zero, a suitable width must be guessed by the `ImpactParamerGenerator` itself.
- The `SubCollisionModel` is used to generate individual, potential nucleon-nucleon `SubCollision`s. Two subclasses are available, one called `NaiveSubCollisionModel` which treats nucleons as simple black disks, and one implementing a more advanced model called `DoubleStrikman` described below.
- The `HIInfo` class contains information related to the generated heavy ion events.
- The `HIUserHooks` class is provided to simplify the customization of a model implemented as a `HeavyIons` subclass. It can be used to eg. change the `ImpactParamerGenerator` used, in a way similar to how the `UserHooks` and `MergingHooks` classes are used.

### Angantyr - the default heavy ion model

The default model in PYTHIA is called Angantyr and is inspired by the old Fritiof model [And86] with improvements described in [Bie16a]. The main idea is to stack parton level events, corresponding to individual nucleon-nucleon sub-collisions, on top of each other and hadronise them together.
Please note: although it is possible to use Rope Hadronisation in heavy ion collisions, these two modules have not yet been validated to work properly together. Also the parameters in the model have not been properly tuned, so the results from running must not be taken as definitive predictions.

To determine which projectile nucleon interacts with which target nucleon, special care is taken to determine in which way the nucleons interact. In a standard Glauber calculations one typicaly only cares about if a sub-collision is inelastic or not, but in Angantyr this is divided up, so that each inelastic sub-collision can either be single-diffractive, double-diffractive or absorptive (ie. non-diffractive). To achieve this, Angantyr uses a model with fluctuating radii of the nucleons resulting in a fluctuating nucleon-nucleon cross section inspired by the model by Strikman et al. [Alv13]. The model for this includes a number of parameters which should be fitted to reproduce inclusive nucleon-nucleon cross sections. To be consistent, the values used comes from PYTHIA's internal model of total cross sections.

The default model for nucleon fluctuations has three parameters, the general fitting machinery in `SubCollisionModel` allows for up to eight parameters.

`pvec` HeavyIon:SigFitDefPar (`default = 17.24,2.15,0.33,0.0,0.0,0.0,0.0,0.0`)
These are the default values of the parameters of the `SubCollisionModel` in Angantyr. They will be used as starting point when fitting to the inclusive nucleon cross sections.

The fitting procedure in `SubCollisionModel` is a kind of genetic algorith where a population of parameter values are allowed to evolve for a number of generations. In the end the the parameter set in the final population which gives the best inclusive cross sections is picked. Eight different cross sections may be fitted to but it is possible to select only some of them:

`pvec` HeavyIon:SigFitErr (`default = 0.02,0.02,0.1,0.05,0.05,0.0,0.1,0.0`; `minimum = 0.0`; `maximum = 1.0`)
The relative error assumed in the calculation of goodness of fit corresponding to the different cross sections fitted to. The cross sections are obtained from the `SigmaTotal` and are given as (in order) total, non-diffractive, double diffractive, wounded target, wounded projectile, central diffractive, and elastic cross sections, and in addition the elastic slope parameter. A relative error of zero for one of these cross sections means the corresponding cross section not be used in the fit.

`mode` HeavyIon:SigFitNInt (`default = 100000`; `minimum = 0`)
The number of integration points used for each parameter setting to calculate the cross sections.

`mode` HeavyIon:SigFitNPop (`default = 20`; `minimum = 1`)
The number individuals (parameter settings) in a population in each generation.

`mode` HeavyIon:SigFitNGen (`default = 20`; `minimum = 0`)
The number of generation used in the genetic algorithm. If set to zero, no fitting will be performed and the values in `HeavyIon:SigFitDefPar` will be used.

`parm` HeavyIon:SigFitFuzz (`default = 0.2`; `minimum = 0.0`; `maximum = 0.5`)
A parameter determining the probability that an individual parameter setting will evolves further away from the best parameter set in each generation.

`flag` HeavyIon:SigFitPrint (`default = on`)
fitting procedure. If on, extensive information about the fitting will be printed.

`mode` Angantyr:CollisionModel (`default = 1`; `minimum = 0`; `maximum = 2`)
The Angantyr model has a couple of option for the SubCollisionModel
`option` 0 : A simplified model with fixed nucleon radii. its normal machinery.
`option` 1 : The default model with fluctuating radii and cross sections.
`option` 2 : Fluctuating radii and cross sections but different treatment of opacity.

`flag` Angantyr:GlauberOnly (`default = off`)
event generation will stop after SubCollisions has been determined, allowing the user to read out the nucleon configuration only.

After all possible nucleon-nucleon sub-collisions has been determined, they are ordered in increasing nucleon-nucleon impact parameter. This list is then gone through in order several time. First all absorptive sub-collisions are treated. One full nucleon-nucleon non-diffractive minimum bias event is generated for each possible absorptive sub-colision. These are also ordered in impact parameter. Note that one target nucleon can interact absorptively with several target nucleons, in a first round only those absorptive sub-collisions involving nucleons that have not already interacted absorptively are are assigned a non-diffractive event.

If PYTHIA is not set up to generate minimum bias events, one or more of the generated non-diffractive events will be replaced by events generated with the selected signal process, and the cross section reported will be modified accordingly.

In a second round only those potential absorptive sub-collisions are considered where one nucleon has already been assinged a full non-diffractive event. In the Angantyr model it is then assumed that the other nuclean will contribute to the final state as if it had just been diffractively excited. Therefore a corresponding single-diffractive event is generated, the elastically scattered beam particle is discarded and the rest is added to the previous non-diffractive event, shuffling a bit with the kinematics so that the total emergy and momentum is conserved.

To generate these single-diffraction events to emulate multiple absorptive sub-collisions a special `Pythia` object is used. To allow flexibility this object need not have exactly the same settings as the the one generating events for normal single-diffraction sub-collisions. To manipulate this `Pythia` object a special form of settings can be used. All settings available for `Diffraction`, `MultipartonInteractions`, `PDF`, `SigmaDiffractive` and `PDF` can be set separately for this `Pythia` object by prefixing their names with `HI`. As an example, setting `HISigmaDiffractive:PomFlux` and `HIPDF:PomSet` will set the `SigmaDiffractive:PomFlux` and `PDF:PomSet` options for this `Pythia` object.

`mode` Angantyr:SASDmode (`default = 4`; `minimum = 0`; `maximum = 4`)
Determines how to generate single-diffraction events as secondary absorptive (SASD) sub-collisions.
`option` 0 : Standard singel-diffraction events as speicfied by `HIDiffraction` settings above.
`option` 1 : Always use `HIPDF:PomSet = 11` and use the same initial `HIMultipartonInteractions:pT0Ref` as for non-diffractive events for the total nucleon-nucleon collision energy, independent of the mass of the diffractive system.
`option` 2 : (Experimental) As for option `1` but also rescale the pomeron proton non-diffractive cross section to match the pp non-diffractive one.
`option` 3 : (Experimental) As for option `1` but use the full nucleon-nucleon cross section for the non-diffractive nucleon-Pomeron in the multiple interaction machinery. Also rescale the Pomeron PDF with the log of the ratio of maximum and minimum Pomeron-nucleon collision energy.
`option` 4 : As for option `3` but no rescaling of the Pomeron PDF.

`mode` Angantyr:impactMode (`default = 2`; `minimum = 0`; `maximum = 2`)
Determines how to bias non-diffractive minimum-bias sub-collisions in pythia to be appropriately central.
`option` 0 : If we have N pirmary sub-collisions and Na secondary sub-collisions, generate N+Na non-diffractive events and pick the N most central.
`option` 1 : Use UserHooks to force Pythia to produce events with a particular impact parameter for the N primary sub collisions according to the generated impact parameter in the SubCollisionModel.
`option` 2 : As for option `1` but also the secondary absorptive sub-collisions have their impact parameter set.

`parm` Angantyr:impactFudge (`default = 0.85`; `minimum = 0.0`; `maximum = 4.0`)
Multiplicative factor used to compensate for the fact that the `SubColllisionModel` in Angantyr may have a different impact parameter profile than what is assumed in the MPI overlap calculation in Pythia.

`mode` Angantyr:SDTries (`default = 1`; `minimum = 1`)
When adding single diffractive sub-collisions to other sub-collisions, there might not be enough energy for the diffractive mass. One option here is to say that the diffractive sub-event simply fails, but setting this larger than unity allows for regenerating the single diffractive sub-event a number of times to see if a small enough diffractive system is produced.

`mode` Angantyr:SDRecoil (`default = 1`; `minimum = 1`; `maximum = 2`)
Determines which particles in a primary sub-collision will take the recoil when adding single diffractive sub-collisions to other sub-collisions. The choice may be overridded by a user-defined `HIUserHooks::findRecoilers` function.
`option` 1 : Only elastically scattered nucleons and nucleon remnants will take recoil.
`option` 2 : All particles outside the added diffractive system's rapidity range are considered.

`flag` Angantyr:SDTest (`default = off`)
Used in conjunction with `HeavyIon:mode = 2` and proton beams to generate single diffractive events that would be used as secondary non-diffractive scatterings in the Angantyr heavy ion model for the given nucleon energies. Used for tuning special `HI`-prefixed parameters of the secondary absorptive sub-collisions.

`parm` Angantyr:SDTestB (`default = -1.0`)
In conjunction with `Angantyr:SDTest = on` and `Angantyr:impactMode = 2` only pick diffractive events with a particular impact parameter (as defined by the scaled value given in `Info::bMPI()`). If negative, the standard impact parameter distribution is used.

After all absorptive sub-collisions have been dealt with, the diffractive and elastic sub-collisions are dealt with in a similar way. In the end there will be a number of parton level events which are finally stacked together, and then hadronised. Finally nucleus remnants constructed from the non-interacting nucleans, are added to complete the full nucleaus-nucleus collision.