<chapter name="Heavy Ion Collisions"> 
 
<h2>Heavy Ion Collisions</h2> 
 
PYTHIA includes a facility in which simulation of heavy ion collisions can 
be implemented through models which combine several nucleon-nucleon collisions 
into one heavy ion collision. One such model, 
called <a href="#Angantyr" target="page">Angantyr</a>, is provided with PYTHIA 
and is in part inspired by the old Fritiof program from the Lund group 
<ref>And87</ref> with recent improvements <ref>Bie16a</ref>. 
 
<p/> 
In the following documentation, there is a split between the general 
facility in which a heavy ion model can be implemented, and the 
concrete implementation of Angantyr which uses the facility to 
implement a model. In order to run Angantyr, several settings from the 
base facility must, however, be used, so it is not advisible simply to 
skip to that section. 
 
<p/> 
The implementation of the heavy ion facility is split between two main 
classes and a number of helper classes. The main classes are: 
 
<p/> 
The <code>HIUserHooks</code> class is provided to simplify the 
customization of a model implemented as a <code>HeavyIons</code> 
subclass. It can be used to eg. change the 
<code>ImpactParameterGenerator</code> used, in a way similar to how 
the <code>UserHooks</code> and <code>MergingHooks</code> 
classes are used. 
 
<p/> 
The <code>HeavyIons</code> class is very simple and flexible and basically 
only specifies that the <code>HeavyIons::init()</code> and 
<code>HeavyIons::next()</code> functions are overridden in a 
subclass. But the additional helper classes should be generic enough 
to be used by any model implemented. 
 
<h3>Heavy Ion beam selection</h3> 
 
A heavy ion beam is selected in the same way as any other beams' 
<aloc href="BeamParameters">beam parameters</aloc>, ie. by specifying 
the PDG particle id for the two beams.  A PDG id code for nuclei is on 
the form 100ZZZAAAI. To be able to specify a certain nucleus as a beam 
particle, the particle must be available in the 
<aloc href="ParticleDataScheme"> particle data scheme</aloc>, a number of 
nuclei are already added, including negative numbers for the 
corresponding anti-particle:<br/> 
<ul> 
 <li><sup>2</sup>H: <code>1000010020</code></li> 
 <li><sup>4</sup>He:  <code>1000020040</code></li> 
 <li><sup>6</sup>Li:  <code>1000030060</code></li> 
 <li><sup>12</sup>C:  <code>1000060120</code></li> 
 <li><sup>16</sup>O:  <code>1000080160</code></li> 
 <li><sup>63</sup>Cu:  <code>1000290630</code></li> 
 <li><sup>84</sup>Kr:  <code>1000360840</code></li> 
 <li><sup>129</sup>Xe:  <code>1000541290</code></li> 
 <li><sup>197</sup>Au:  <code>1000791970</code></li> 
 <li><sup>208</sup>Pb:  <code>1000822080</code></li> 
</ul> 
More can be added by the user, using the function 
<code>ParticleData::addParticle</code>, documented in the 
<aloc href="ParticleDataScheme">particle data scheme</aloc>, 
but be mindful that a suitable  model geometry must be available for the 
nucleus added, see the available 
<a href="#NucleusModel" target="page">nucleus models</a> below. 
 
Angantyr supports beam switching if <code>Beams:allowIDAswitch</code> is 
turned on. In this case, <code>idA</code> is allowed to be any hadron, while 
<code>idB</code> is allowed to be a proton, nucleon or any ion. 
 
<h3>Top level flags</h3> 
 
<modepick name="HeavyIon:mode" default="1" min="1" max="2"> 
This is the master switch for heavy ions, and determines the mode 
of operation of the HeavyIon model. 
<option value="1">  The heavy ion machinery will be used in case of ion beams. 
</option> 
<option value="2">  Even collisions without ions are treated using 
the heavy ion machinery. (Typically only used 
for debugging purposes.) 
</option> 
</modepick> 
 
<p/> 
 
If <code>HeavyIon:mode</code> is on, the normal initialization in 
<code>Pythia::init()</code> is early on diverted to an object with 
the base class <code>HeavyIons</code> which may instantiate 
secondary <code>Pythia</code> 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 
<code>HeavyIons::init()</code> function. Subsequent calls to 
<code>Pythia::next()</code> will then also be diverted to the virtual 
function <code>HeavyIons::next()</code> which will be responsible for 
building up the heavy ion collision. The final event will be available 
in the primary <code>Pythia</code> object. 
 
<flag name="HeavyIon:showInit" default="on"> 
<strong>Please note:</strong> this flag is not currently in use due to 
conflicts with the <aloc href="Parallelism">Parallelism</aloc> 
framework, but is expected to be reintroduced in the future. 
Output detailed initialization information from the heavy ion 
model. Typically there will be several <code>Pythia</code> objects 
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 <code>Pythia</code> object will be shown. 
</flag> 
 
The impact parameter between two colliding nuclei, is sampled by the 
code contained in <code>ImpactParameterGenerator</code>. 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 name="HeavyIon:bWidth" default="0.0" min="0.0"> 
The width in fermi of the distribution by which the impact parameter 
is sampled. If zero, a suitable width will be guessed by the 
<code>ImpactParameterGenerator</code> itself. 
</parm> 
 
<parm name="HeavyIon:bWidthCut" default="3.0" min="0.0"> 
An additional upper cut for impact parameters, forcing it to always be 
smaller than <code>HeavyIon:bWidthCut</code> times 
<code>HeavyIon:bWidth</code>. 
</parm> 
 
<flag name="HeavyIon:forceUnitWeight" default="off"> 
Allows completely flat generation of impact parameter in within 
<code>HeavyIon:bWidthCut</code>, giving all events unit weight. 
</flag> 
 
<h3>Nucleus Models - the nuclear geometry</h3> 
 
Several models and parametrizations exist to describe the distribution 
in the radial density of nucleons in a nucleus. The 
<code>NucleusModel</code> class is a base class for implementing such 
models. There are five ready-made models implemented already. When 
using Angantyr, the nuclear models can be selected using the following 
settings. 
 
<modepick name="Angantyr:NucleusModelA" default="1" min="1" max="5"> 
</modepick> 
<modepick name="Angantyr:NucleusModelB" default="1" min="1" max="5"> 
Select the model for nuclear geometry for beam A and B respectively. 
Models and associated parameters are documented below. 
<option value="1"> GLISSANDO Woods-Saxon. This default model is suitable for 
large nuclei. 
</option> 
<option value="2"> Standard Woods-Saxon. 
</option> 
<option value="3"> Harmonic Oscillator Shell model. 
</option> 
<option value="4"> Gaussian model. 
</option> 
<option value="5"> Hulthen model. 
</option> 
</modepick> 
 
<p/> 
For large nuclei, the Woods-Saxon potential is suitable. The 
<code>WoodsSaxonModel</code>, implements a standard Woods-Saxon 
distribution with parameters to be input by the user, and the 
<code>GLISSANDOModel</code>, implements the more advanced model from 
<ref>Bro09,Ryb14</ref>. For light nuclei (16O and lighter), several options 
are implemented. The <code>HulthenModel</code> implements the Hulthen 
potential suitable for deuterons, the <code>HOShellModel</code> a harmonic 
oscillator shell model density and <code>GaussianModel</code> a Gaussian 
radial distribution. Finally it is possible to read in externally generated 
nuclear configurations from a file, in the <code>ExternalNucleusModel</code>. 
 
<p/> 
If a user wishes to specify own parameters for the <code>NucleusModel</code>s, 
parameters must be specified for beam A and B separately, using prefix 
<code>HeavyIonA:</code> or <code>HeavyIonB:</code> as specified below. 
 
<h4>Standard Woods-Saxon</h4> 
For sufficiently large nuclei, the Woods-Saxon distribution:<br/> 
<ei>rho(r) = rho_0/(1 + exp((r-R)/a))</ei> <br/> 
is a suitable choice. 
The model has two parameters, which can be set by: 
<parm name="HeavyIonA:WSR" default="0.0" min="0.0"> 
</parm> 
<parm name="HeavyIonB:WSR" default="0.0" min="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 <ref>Ryb14</ref>, based on the number of nucleons in the 
nuclei and whether a hard core is used or not. 
</parm> 
 
<parm name="HeavyIonA:WSa" default="0.0" min="0.0"> 
</parm> 
<parm name="HeavyIonB:WSa" default="0.0" min="0.0"> 
The <i>skin width</i> 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 <ref>Ryb14</ref>, based on the number of 
nucleons in the nucleus and whether a hard core is used or not. 
</parm> 
 
<h4>GLISSANDO Woods-Saxon</h4> 
In <ref>Ryb14</ref> it was shown that for <ei>a=0.54</ei> fm, and 
sufficiently heavy nuclei, the Woods-Saxon radius parameter 
is well approximated by: <br/> 
<ei>R = (1.1 A^(1/3) - 0.656 A^(-1/3))</ei>. <br/> 
These values are used for all nuclei when this model is selected. 
 
<h4>Harmonic Oscillator Shell</h4> 
For lighter nuclei, a two-parameter Harmonic Oscillator Shell model 
is implemented. Here: <br/> 
<ei>rho(r) = 4/(pi^(3/2)C^3)(1 + (A - 4)/6 * (r/C)^2)exp(-r^2/C^2)</ei> 
with:<br/> 
<ei>C = (5/2 - 4/A)^(-1) (&lt; r^2&gt;_A - &lt;r^2&gt;_p)</ei>.<br/> 
The two model paramters are <ei>&lt; r^2&gt;_A</ei> (nuclear charge radius 
squared) and <ei>&lt;r^2&gt;_p</ei> (proton charge radius squared). These can 
be set, in units of fm^2. 
<parm name="HeavyIonA:HONuclearChargeRadius" default="0.0" min="0.0"> 
</parm> 
<parm name="HeavyIonB:HONuclearChargeRadius" default="0.0" min="0.0"> 
</parm> 
If nothing is selected, the program includes the following reasonable 
defaults for the following often used nuclei, using units of fm^2 throughout: 
<table style="width:30%"> 
  <tr> 
    <th>Nucleus</th> 
    <th>w. hard core</th> 
    <th>w./o. hard core</th> 
  </tr> 
  <tr> 
    <td><sup>4</sup>He</td> 
    <td>2.45</td> 
    <td>2.81</td> 
  </tr> 
  <tr> 
    <td><sup>6</sup>Li</td> 
    <td>6.4</td> 
    <td>6.7</td> 
  </tr> 
  <tr> 
    <td><sup>7</sup>Be</td> 
    <td>6.69</td> 
    <td>7.00</td> 
  </tr> 
  <tr> 
    <td><sup>8</sup>Li</td> 
    <td>5.1</td> 
    <td>5.42</td> 
  </tr> 
  <tr> 
    <td><sup>9</sup>Be</td> 
    <td>6.0</td> 
    <td>6.35</td> 
  </tr> 
  <tr> 
    <td><sup>10</sup>B</td> 
    <td>5.5</td> 
    <td>5.89</td> 
  </tr> 
  <tr> 
    <td><sup>11</sup>B</td> 
    <td>5.36</td> 
    <td>5.79</td> 
  </tr> 
  <tr> 
    <td><sup>12</sup>C</td> 
    <td>5.66</td> 
    <td>6.10</td> 
  </tr> 
  <tr> 
    <td><sup>13</sup>C</td> 
    <td>5.6</td> 
    <td>6.06</td> 
  </tr> 
  <tr> 
    <td><sup>14</sup>N</td> 
    <td>6.08</td> 
    <td>6.54</td> 
  </tr> 
  <tr> 
   <td><sup>15</sup>N</td> 
    <td>6.32</td> 
    <td>6.79</td> 
  </tr> 
  <tr> 
    <td><sup>16</sup>N</td> 
    <td>6.81</td> 
    <td>7.29</td> 
  </tr> 
</table> 
Note that you may need to add the nucleus as a particle as well. 
<p/> 
 
<parm name="HeavyIonA:HOProtonChargeRadius" default="0.7714" min="0.0"> 
</parm> 
<parm name="HeavyIonB:HOProtonChargeRadius" default="0.7714" min="0.0"> 
The proton charge radius squared. Units of fm^2. 
</parm> 
 
<h4>Gaussian model</h4> 
The Gaussian model parametrizes the nuclear radial density as a 
Gaussian distribution. While this may not be a fully adequate physics 
based model, it provides a starting point for parametrization of 
some light nuclei. The model has a single parameter, the with of 
the distribution, intepreted as a nuclear charge radius. 
 
<parm name="HeavyIonA:GaussianChargeRadius" default="7.7" min="0.0"> 
</parm> 
<parm name="HeavyIonB:GaussianChargeRadius" default="7.7" min="0.0"> 
The charge radius of the Gaussian parametrization. Units of fm. The default 
value gives a reasonable description of O16. 
</parm> 
 
<h4>Hulth&eacute;n model</h4> 
The Hulth&eacute;n distribution <ref>Hul42</ref> is given by:<br/> 
<ei>rho(r) = rho_0(exp(-a r) - exp(-b r))</ei><br/> 
where <ei>b</ei> term regulates the <ei>a</ei> term at small distances so 
that <ei>rho(0) = 0</ei>. The <ei>a</ei> term can be written as <ei>sqrt(m 
E)</ei>, where <ei>m</ei> is the mass of the nucleon and <ei>E</ei> is 
the binding energy. The <ei>b</ei> parameter can be written in terms 
of <ei>a</ei> using the triplet effective range parameter as roughly 
<ei>3a</ei> <ref>Adl75</ref>. 
<parm name="HeavyIonA:HulthenA" default="0.4" min="0.0"> 
</parm> 
<parm name="HeavyIonB:HulthenA" default="0.4" min="0.0"> 
Hulthen a-parameter, units of fm^-1. Note that b > a > 0 always. 
</parm> 
<parm name="HeavyIonA:HulthenB" default="1.2" min="0.0"> 
</parm> 
<parm name="HeavyIonB:HulthenB" default="1.2" min="0.0"> 
Hulthen b-parameter, units of fm^-1. Note that b > a > 0 always. 
</parm> 
 
<h4>Externally generated configuration</h4> 
For certain purposes it might be appropriate for a user to read 
in nuclear configurations from a file stored on disk, produced 
by another program. The <code>ExternalNucleusModel</code> acts 
as an interface for this operation. The file must be of the 
following format:<br/> 
<ul> 
<li>One line corresponds to one nucleus.</li> 
<li>All nucleons in the nucleus must have an x, y and z coordinate, 
in that order, in the nucleus COM system, in units of fm. </li> 
<li>A line will thus have 3 * A (where A is 
the mass number) entries, separated by a whitespace character.</li> 
<li>Any line containing the "#" character is treated as a 
comment, and thus skipped.</li> 
</ul> 
Isospin information cannot currently by added, and is assigned 
randomly.<br/> 
When the configurations are read in, they will be shuffled randomly, 
in order to avoid collisions between identical configurations. When 
the list of configurations is exhausted, elements will be reshuffled 
again.<br/> 
Note: All configurations in the given file will be read in when Pythia 
is initialized. If your file is very large, this will consume a large 
amount of memory, so this is typically only advised for a few thousand 
configurations, or at least not orders of magnitude more. 
<word name="HeavyIonA:externalNucleusFile" default=""> 
</word> 
<word name="HeavyIonB:externalNucleusFile" default=""> 
The name of the file to be read in. Must be accessible, no default 
provided. 
</word> 
<flag name="HeavyIonA:externalShuffle" default="on"> 
</flag> 
<flag name="HeavyIonB:externalShuffle" default="on"> 
Randomly shuffle configurations when read in, and when the list 
is exhausted. Turning shuffling off is allowed mostly for 
debug purposes. 
</flag> 
 
<h4>Nucleon hard core: Common parameters</h4> 
As an attempt to model multi-nucleon correlations inside nuclei, 
nucleons have a "hard core", which cannot overlap with other 
nucleons' hard cores, when nucleons are sampled. All models 
except for the Hulthen model (where the same behaviour is 
directly encoded into the density function) have the 
possibility for either a fixed-size hard core of a 
given width, or a Gaussian hard core, where the hard core 
radius is sampled from a Gaussian at the per-nucleon level. 
The hard core repulsion is switched on by default. 
 
<flag name="HeavyIonA:HardCore" default="on"> 
</flag> 
<flag name="HeavyIonB:HardCore" default="on"> 
Assume that there is a minimum distance between nucleons defined by a hard 
core radius in <code>HeavyIon:HardCoreRadius</code>. 
</flag> 
<parm name="HeavyIonA:HardCoreRadius" default="0.9" min="0.0"> 
</parm> 
<parm name="HeavyIonB:HardCoreRadius" default="0.9" min="0.0"> 
The hard core radius in units of fm, defining the minimum 
distance between nucleons in a nucleus. 
</parm> 
<flag name="HeavyIonA:GaussHardCore" default="off"> 
</flag> 
<flag name="HeavyIonB:GaussHardCore" default="off"> 
Option to use a Gaussian profile of the hard core instead of a sharp 
cut-off, inspired by <ref>Bay95</ref>. 
</flag> 
 
<h3>Nucleons and subcollisions</h3> 
 
The geometry models above, wil generate two lists of <code>Nucleon</code>s. 
Collisions between individual projectile and target nucleons are 
generated by <code>SubCollisionModel</code>s, outputting individual, 
potential nucleon-nucleon <code>SubCollision</code>s. 
 
<h4>Nucleons</h4> 
 
The <code>Nucleon</code> class represents a single nucleon in a nucleus. 
The class contains several methods for accessing information and 
modifying state, here only the ones deemed useful for a user are mentioned. 
 
<method name="int Nucleon::id()"> 
The nucleon particle id. Currently limited to protons and neutrons, ie. 
no hypernuclei possible. 
</method> 
 
<method name="const Vec4&amp; Nucleon::nPos()"> 
The nucleon position relative to the nucleus center. 
</method> 
 
<method name="const Vec4&amp; Nucleon::bPos()"> 
The nucleon absolute position in impact parameter space. 
</method> 
 
<method name="void Nucleon::bShift(const Vec4&amp; bvec)"> 
Shift the nucleon absolute position in impact parameter space. 
</method> 
 
<method name="Status Nucleon::status()"> 
The nucleon status, meaning whether and how it is participating. 
It can take the following values: 
<ul> 
<li><code>Nucleon::UNWOUNDED</code>: The nucleon is not participating.</li> 
<li><code>Nucleon::ELASTIC</code>: The nucleon is elastically scattered.</li> 
<li><code>Nucleon::DIFF</code>: The nucleon is diffractively wounded.</li> 
<li><code>Nucleon::ABS</code>: The nucleon is absorptively wounded.</li> 
</ul> 
</method> 
 
<h4>Subcollisions</h4> 
 
The <code>SubCollision</code> class represents a potential 
nucleon-nucleon collision between a projectile and a target 
<code>Nucleon</code>. From a subcollision, pointers to projectile 
and target nucleons participating can be accessed: 
 
<method name="Nucleon* SubCollision::proj"> 
</method> 
<methodmore name="Nucleon* SubCollision::targ"> 
Pointers to projectile and target nucleons are public members of the 
<code>SubCollision</code> class 
</methodmore> 
 
The impact parameter distance between nucleons participating 
in a given subcollision can also be accessed directly. 
 
<method name="double SubCollision::b"> 
</method> 
<methodmore name="double SubCollision::bp"> 
The impact parameter distance between the two participating nuclei, 
respectively in units of fm and scaled like in Pythia to have unit 
average for non-diffractive collisions. 
</methodmore> 
 
Information about whether a given potential sub-collision was actually 
realized as a final state particle producing sub-collision, or if 
it failed is given as: 
<method name="bool SubCollision::failed"> 
</method> 
 
Finally the type of subcollision can be accessed by a method: 
<method name="CollisionType SubCollision::type()"> 
The subcollision type, meaning how the two nucleons interacted. It 
can take the following values: 
<ul> 
<li><code>SubCollision::NONE</code>: Not a collision.</li> 
<li><code>SubCollision::ELASTIC</code>: Elastic scattering.</li> 
<li><code>SubCollision::SDEP</code>: Projectile is diffractively 
excited.</li> 
<li><code>SubCollision::SDET</code>: Target is diffractively 
excited.</li> 
<li><code>SubCollision::DDE</code>: Both are diffractively 
excited.</li> 
<li><code>SubCollision::CDE</code>: Central diffraction.</li> 
<li><code>SubCollision::ABS</code>: Absorptive (inelastic 
non-diffractive) interaction.</li> 
</ul> 
</method> 
 
<h4>Subcollision models</h4> 
 
Presently three <code>SubCollisionModel</code>s are available.  The 
<code>BlackSubCollisionModel</code>, which is the simplest black disk 
model possible, the <code>NaiveSubCollisionModel</code> which on top 
of a black disk model, allows less central subcollisions to be 
diffractive or elastic, and a more elaborate treatment called 
<code>DoubleStrikman</code>, described 
<a href="#Angantyr" target="page">below.</a> 
 
<p/> 
The main idea behind currently implemented 
<code>SubCollisionModel</code>s, is that parameters should be fitted 
from semi-inclusive cross sections. Thus, the code includes a fitting 
machinery, based on a simple genetic algorithm.  Cross sections are 
taken form the standard Pythia 
<aloc href="TotalCrossSections">total cross sections</aloc>. 
Parameters for the models are therefore not set 
in the normal sense, but initial values for the fit are set instead, 
an example for the default model given below. 
 
<p/> 
The default model for nucleon fluctuations has three parameters, the 
general fitting machinery in <code>SubCollisionModel</code> allows for 
up to eight parameters. 
 
<pvec name="HeavyIon:SigFitDefPar" default="{}"> 
These are the default values of the parameters of the 
<code>SubCollisionModel</code> in Angantyr. They will be used as 
starting point when fitting to the inclusive nucleon cross sections. If left 
empty, the values will be set to the model default. 
</pvec> 
 
<parm name="HeavyIon:SigFitDefAvNDb" default="0.0"> 
This is the average non-diffractive impact parameter assumed in the 
<code>SubCollisionModel</code> in Angantyr. It is something that comes out 
the cross section fitting procedure but can be specified here if the fitting 
procedure is omitted and the <code>HeavyIon:SigFitDefPar</code> 
parameters are used instead. 
</parm> 
 
<p/> 
 
The fitting procedure in <code>SubCollisionModel</code> 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 name="HeavyIon:SigFitErr" 
      default="{0.02,0.02,0.1,0.05,0.05,0.0,0.1,0.15}" min="0.0" max="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 
<aloc href="TotalCrossSections"><code>SigmaTotal</code></aloc> 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. 
</pvec> 
 
<mode name="HeavyIon:SigFitNInt" default="100000" min="0"> 
The number of integration points used for each parameter setting to 
calculate the cross sections. 
</mode> 
 
<mode name="HeavyIon:SigFitNPop" default="20" min="1"> 
The number individuals (parameter settings) in a population in each 
generation. 
</mode> 
 
<mode name="HeavyIon:SigFitNGen" default="20" min="0"> 
The number of generation used in the genetic algorithm. If set to 
zero, no fitting will be performed and the values in 
<code>HeavyIon:SigFitDefPar</code> will be used. 
</mode> 
 
<parm name="HeavyIon:SigFitFuzz" default="0.2" min="0.0" max="0.5"> 
A parameter determining the probability that an individual parameter 
setting will evolves further away from the best parameter set in each 
generation. 
</parm> 
 
<flag name="HeavyIon:SigFitPrint" default="on"> 
Controls the output from the fitting procedure. If on, extensive 
information about the fitting will be printed. 
</flag> 
 
<h3>Obtaining event information</h3> 
 
The <code>HIInfo</code> class contains information related to the 
generated heavy ion events. In a run, it can be obtained from the 
usual <aloc href="EventInformation">Info</aloc> object, by calling 
<code>pythia.info.hiInfo()</code>, which returns a pointer to the 
current <code>HIInfo</code> object. The methods of this class are: 
<method name="double HIInfo::b()"> 
The impact parameter distance of the heavy ion event. 
</method> 
<method name="double HIInfo::T()"> 
The summed elastic amplitude for this event, from which cross 
sections at Glauber level are calculated. 
</method> 
<method name="int HIInfo::nAttempts()"> 
The number of attempted impact parameter points. 
</method> 
<method name="int HIInfo::nAccepted()"> 
The number of produced events. 
</method> 
 
Several methods exist to extract information from the Glauber 
calculation. Caution should be taken when using this information 
directly, under the assumption that obtained numbers correspond 
one-to-one to numbers obtained from another calculation, as performed 
eg. by an experiment. Since they are all model dependent quantities, a 
direct comparison can often not be made. 
 
<p/> 
A user is often better off by extracting the full set of 
subcollisions, and extracting the relevant information from that. 
 
<method name="multiset&lt;SubCollision&gt;* HIInfo::subCollisionsPtr()"> 
A (pointer to) a multiset containing all <code>SubCollision</code>s of 
the current event. Can be modified by the user. 
</method> 
<method name="void HIInfo::subCollisionsPtr(multiset&lt;SubCollision&gt; 
* sPtrIn)"> 
Sets this event's subcollision. Starting point for a user who wishes 
to interface their own or an external Glauber calculation. 
</method> 
<method name="int HIInfo::nCollTot()"> 
The total number of subcollisions in the current event. 
</method> 
<method name="int HIInfo::nCollND()"> 
The number of non-diffractive subcollisions in the current 
event. 
</method> 
<method name="int HIInfo::nCollSDP()"> 
The number of single diffractive projectile excitation 
subcollisions in the current event. 
</method> 
<method name="int HIInfo::nCollSDT()"> 
The number of single diffractive target excitation 
subcollisions in the current event. 
</method> 
<method name="int HIInfo::nCollDD()"> 
The number of double diffractive subcollisions in the current 
event. 
</method> 
<method name="int HIInfo::nCollCD()"> 
The number of central diffractive subcollisions in the 
current event. 
</method> 
<method name="int HIInfo::nCollEL"> 
The number of elastic subcollisions in the current event. 
</method> 
<method name="int HIInfo::nPartProj()"> 
</method> 
<methodmore name="int HIInfo::nPartTarg()"> 
The number of interacting projectile/target nucleons in the current 
event (number of participants). 
</methodmore> 
<method name="int HIInfo::nAbsProj()"> 
</method> 
<methodmore name="int HIInfo::nAbsTarg()"> 
The number of absorptively interacting projectile/target nucleons in 
the current event (number of absorptive participants). 
</methodmore> 
<method name="int HIInfo::nDiffProj()"> 
</method> 
<methodmore name="int HIInfo::nDiffTarg()"> 
The number of diffractively interacting projectile/target nucleons in 
the current event (number of diffractive participants). 
</methodmore> 
<method name="int HIInfo::nElProj()"> 
</method> 
<methodmore name="int HIInfo::nElTarg()"> 
The number of elastically interacting projectile/target nucleons in 
the current event (number of elastic participants). 
</methodmore> 
<method name="double HIInfo::glauberTot()"> 
</method> 
<methodmore name="double HIInfo::glauberND()"> 
</methodmore> 
<methodmore name="double HIInfo::glauberINEL()"> 
</methodmore> 
<methodmore name="double HIInfo::glauberEL()"> 
</methodmore> 
<methodmore name="double HIInfo::glauberDiffT()"> 
</methodmore> 
<methodmore name="double HIInfo::glauberDiffP()"> 
</methodmore> 
<methodmore name="double HIInfo::glauberDDiff()"> 
</methodmore> 
<methodmore name="double HIInfo::glauberBSlope()"> 
Various semi-inclusive cross sections obtained from the Glauber calculation 
(total, non-diffractive, total inelastic, elastic, diffractive excitation of 
the target and projectile or both, elastic b-slope, respectively). Note that 
these are in general not the same as the generated cross sections, since 
Angantyr does not generate elastic scatterings correctly. Also the error of 
these cross sections are available from functions of the form 
<code>HIInfo::glauberTotErr()</code>. The cross sections are given in 
millibarns and the slope in Gev<sup>-2</sup>. 
</methodmore> 
<method name="double HIInfo::weight()"> 
The weight for this collision. Note that heavy ion weights are 
propagated to the 
<aloc href="CrossSectionsAndWeights">normal weights system</aloc>, 
and a call to <code>pythia.info.weight()</code> contains 
the heavy ion weight as well.  Normally a user would have no reason to 
access this method directly. 
</method> 
<method name="double HIInfo::weightSum()"> 
The sum of weights for all produced events up to this point. Note that 
heavy ion weights are propagated to the 
<aloc href="CrossSectionsAndWeights">normal weights system</aloc>, 
and a call to <code>pythia.info.weightSum()</code> contains the heavy 
ion weights as well. Normally a user would have no reason to access this 
method directly. 
</method> 
 
<a name="Angantyr"></a> 
<h3>Angantyr - the default heavy ion model</h3> 
 
The default model in PYTHIA is called Angantyr and is inspired by the 
old Fritiof model <ref>And86</ref> with improvements described in 
<ref>Bie16a</ref>. The main idea is to stack parton level events, 
corresponding to individual nucleon-nucleon sub-collisions, on top of 
each other and hadronize them together.<br/> 
<p/> 
<strong>Please note:</strong> <br/> 
<ul> 
<li>Although it is possible to use 
<aloc href="RopeHadronization">Rope Hadronization</aloc> 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.</li> 
<li>A similar warning should be made regarding the use of 
<aloc href="ColourReconnection">Colour Reconnection</aloc> models. By 
default the colour reconnection takes place only inside individual 
nucleon-nucleon sub-collisions, and not in the nucleus-nucleus collision 
as a whole. To get reconnections also between sub-collisions, the 
settings described in <ref>Lon23</ref> should be used.</li> 
</ul> 
<p/> 
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 <i>Glauber</i> 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. <ref>Alv13</ref>, called <code>DoubleStrikman</code>. 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 
<aloc href="TotalCrossSections">total cross sections</aloc>, see above for 
further documentation of this routine. 
<p/> 
 
<modepick name="Angantyr:CollisionModel" default="2" min="0" max="5"> 
The Angantyr model has a couple of option for the 
<code>SubCollisionModel</code>. 
<option value="0"> 
A simplified model with fixed nucleon radii. 
</option> 
<option value="1"> 
The <code>DoubleStrikman</code> model with fluctuating radii 
and cross sections. 
</option> 
<option value="2"> 
Fluctuating radii and cross sections but an alternate treatment of 
opacity (default). 
</option> 
<option value="3"> 
Black disks with no fluctuations, ie. no diffraction. 
</option> 
<option value="4"> 
Model with fluctuations where the projectile and target can have different 
parameters, relevant for hadron-nucleon collisions. Note that this option 
requires much longer initialization time than option 1. Our studies indicate 
that option 1 is sufficiently precise in most cases. 
</option> 
<option value="5"> 
As option 4, but different treatment of opacity. 
</option> 
</modepick> 
 
<flag name="Angantyr:GlauberOnly" default="off"> 
If switched on, the event generation will stop after 
<code>SubCollision</code>s has been determined, allowing the user to 
read out the nucleon configuration only. 
</flag> 
 
<p/> 
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. 
 
<p/> 
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. 
 
<p/> 
 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. 
 
<p/> 
To generate these single-diffraction events to emulate multiple 
absorptive sub-collisions a special <code>Pythia</code> 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 
<code>Pythia</code> object a special form of settings can be used. All 
settings available for 
<aloc href="Diffraction"><code>Diffraction</code></aloc>, 
<aloc href="MultipartonInteractions"> 
  <code>MultipartonInteractions</code></aloc>, 
<aloc href="PDFSelection"><code>PDF</code></aloc>, 
<aloc href="TotalCrossSections"><code>SigmaDiffractive</code></aloc> and 
<aloc href="PDFSelection"><code>PDF</code></aloc> 
can be set separately for this <code>Pythia</code> object by prefixing 
their names with <code>HI</code>. 
 
As an example, setting <code>HISigmaDiffractive:PomFlux</code> and 
<code>HIPDF:PomSet</code> will set the 
<code>SigmaDiffractive:PomFlux</code> and <code>PDF:PomSet</code> 
options for this <code>Pythia</code> object. 
 
<modepick name="Angantyr:SASDmode" default="4" min="0" max="4"> 
Determines how to generate single-diffraction events as secondary 
absorptive (SASD) sub-collisions. 
<option value="0"> 
Standard singel-diffraction events as speicfied by 
<code>HIDiffraction</code> settings above. 
</option> 
<option value="1"> 
Always use <code>HIPDF:PomSet = 11</code> and use the same initial 
<code>HIMultipartonInteractions:pT0Ref</code> as for non-diffractive 
events for the total nucleon-nucleon collision energy, independent of 
the mass of the diffractive system. 
</option> 
<option value="2"> 
(Experimental) As for option <code>1</code> but also rescale the 
pomeron proton non-diffractive cross section to match the pp 
non-diffractive one. 
</option> 
<option value="3"> 
(Experimental) As for option <code>1</code> 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> 
<option value="4"> 
As for option <code>3</code> but no rescaling of the Pomeron PDF. 
</option> 
</modepick> 
 
<modepick name="Angantyr:impactMode" default="2" min="0" max="2"> 
Determines how to bias non-diffractive minimum-bias sub-collisions in 
PYTHIA to be appropriately central. 
<option value="0"> 
If we have <ei>N</ei> primary sub-collisions and <ei>Na</ei> secondary 
sub-collisions, generate <ei>N+Na</ei> non-diffractive events and pick 
the <ei>N</ei> most central. 
</option> 
<option value="1"> 
Use <code>UserHooks</code> to force Pythia to produce events with a 
particular impact parameter for the <ei>N</ei> primary sub collisions 
according to the generated impact parameter in the 
<code>SubCollisionModel</code>. 
</option> 
<option value="2"> 
As for option <code>1</code> but also the secondary absorptive 
sub-collisions have their impact parameter set. 
</option> 
</modepick> 
 
<parm name="Angantyr:impactFudge" default="0.85" min="0.0" max="4.0"> 
Multiplicative factor used to compensate for the fact that the 
<code>SubColllisionModel</code> in Angantyr may have a different 
impact parameter profile than what is assumed in the MPI overlap 
calculation in Pythia. 
</parm> 
 
<mode name="Angantyr:SDTries" default="1" min="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> 
 
<modepick name="Angantyr:SDRecoil" default="1" min="1" max="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 
<code>HIUserHooks::findRecoilers</code> function. 
<option value="1"> 
Only elastically scattered nucleons and nucleon remnants will take 
recoil. 
</option> 
<option value="2"> 
All particles outside the added diffractive system's rapidity range 
are considered. 
</option> 
</modepick> 
 
<flag name="Angantyr:SDTest" default="off"> 
Used in conjunction with <code>HeavyIon:mode = 2</code> 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 
<code>HI</code>-prefixed parameters of the secondary absorptive 
sub-collisions. 
</flag> 
 
<parm name="Angantyr:SDTestB" default="-1.0"> 
In conjunction with <code>Angantyr:SDTest = on</code> and 
<code>Angantyr:impactMode = 2</code> only pick diffractive events with 
a particular impact parameter (as defined by the scaled value given in 
<code>Info::bMPI()</code>). If negative, the standard impact parameter 
distribution is used. 
</parm> 
 
<p/> 
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 hadronized. Finally nucleus 
remnants constructed from the non-interacting nucleans, are added to 
complete the full nucleaus-nucleus collision. 
 
<p/> 
 
It is possible to initialize Angantyr to allow changing the beam energy on 
an event-by-event basis. This is done by setting 
<code>Beams:allowVariableEnergy = on</code>, then changing the energy using 
the <code>Pythia::setKinematics</code> methods. 
When initializing this way, the <code>SubCollisionModel</code> fitting 
procedure calculates the parameter values at several different energies, 
using interpolation to get values between these energy points. 
The following settings are used when variable energies are allowed. 
<parm name="HeavyIon:varECMMin" default="100" min="10"> 
The minimum allowed energy. Note that Angantyr is currently not 
designed to properly handle energies below around 100 GeV. 
</parm> 
<parm name="HeavyIon:varECMMax" default="0"> 
The maximum allowed energy. If it is set to 0, then the largest possible 
value will be given by the CM energy at which Pythia is initialized. 
</parm> 
<mode name="HeavyIon:varECMSigFitNPts" default="5" min="2"> 
Number of eCM points where the <code>SubCollisionModel</code> are calculated. 
The points are logarithmically spaced. 
</mode> 
<flag name="HeavyIon:varECMStepwiseEvolve" default="on"> 
If on, at each evolution point, the algorithm will use the generated 
parameters from the previous point. If off, it start from the default 
parameter set given by <code>HeavyIon:SigFitDefPar</code> at each point. 
</flag> 
<modepick name="HeavyIon:SigFitReuseInit" default="0" min="-2" max="3"> 
If set, the parameters calculated from the evolutionary algorithm can be 
saved/loaded to disk, for faster initialization in subsequent runs. 
<option value="0">Initialize from scratch every time.</option> 
<option value="1">Initialize from scratch, then save configuration.</option> 
<option value="2">Load configuration from file. If the file is not found, 
initialization fails.</option> 
<option value="3">Load configuration from file if it exists, otherwise 
initialize from scratch and save the file.</option> 
<option value="-1">Initialize fit from <code>Init:reuseHeavyIonSigFit</code> 
if not empty. In any case write the fitted parameters to 
<code>Init:reuseHeavyIonSigFit</code>.</option> 
<option value="-2">Same as <code>-1</code> but also read/write the 
setting from/to the file <code>HeavyIon:SigFitInitFile</code>.</option> 
</modepick> 
 
<word name="HeavyIon:SigFitInitFile" default="Angantyr.sigfit"> 
The file where the sigfit configuration is stored. 
</word> 
 
<wvec name="Init:reuseHeavyIonSigFit" default="{}"> 
This is the internal setting where the fitted parameters are stored for 
<code>HeavyIon:SigFitReuseInit &lt; 0</code>. 
</wvec> 
 
<mode name="HeavyIon:SasdMpiReuseInit" default="0" min="-2" max="3"> 
This setting is similar to <code>MultipartonInteractions:reuseInit</code>, 
but pertains to the SASD Pythia subobject used internally by Angantyr. 
<option value="0">current run is self-contained.</option> 
<option value="1">MPI initialization is done as usual, but afterwards 
the results of this initialization are saved on file.</option> 
<option value="2">initialization data is read in from a file, saved 
from a previous initialization, thereby saving time. If the file is not 
found, initialization fails.</option> 
<option value="3">as option 2, but if the file is not found, it will be 
generated and saved after normal initialization.</option> 
<option value="-1">read initialization data from 
<code>Init:reuseSasdMpiInit</code> if not empty. In any case write the 
the data to <code>Init:reuseSasdMPI...</code> setting.</option> 
<option value="-2">Same as <code>-1</code> but also read/write the 
setting from/to the file <code>HeavyIon:SasdMpiInitFile</code>.</option> 
</mode> 
 
<word name="HeavyIon:SasdMpiInitFile" default="Angantyr.sasd.mpi"> 
The file name used to store or read MPI initialization data for the SASD 
Pythia object. It is up to the user to pick a suitable name 
(including path if relevant) for the case at hand. 
</word> 
 
<wvec name="Init:reuseSasdMPIiDiffSys0" default = "{}"> 
This is where the fitted parameters are stored for non-diffractive 
processes. 
</wvec> 
 
<wvec name="Init:reuseSasdMPIiDiffSys1" default = "{}"> 
This is where the fitted parameters are stored for single diffractive 
(XB) processes. 
</wvec> 
 
<wvec name="Init:reuseSasdMPIiDiffSys2" default = "{}"> 
This is where the fitted parameters are stored for single diffractive 
(AX) processes. 
</wvec> 
 
<wvec name="Init:reuseSasdMPIiDiffSys3" default = "{}"> 
This is where the fitted parameters are stored for doubly diffractive 
(AXB) processes. 
</wvec> 
 
 
</chapter> 
 
<!-- Copyright (C) 2025 Torbjorn Sjostrand --> 
