Usage¶

Specifying projectiles¶

The projectile arguments take species abbreviations, e.g. p, Pb, etc. The known species are

For the deuteron, nucleon positions are sampled from the Hulthén wavefunction; for the heavy nuclei, positions are sampled from a Woods-Saxon distribution, either spherically symmetric or deformed as indicated. Copper, xenon, and gold are slightly deformed—slightly enough that a symmetric distribution is a reasonable approximation—therefore both symmetric (Cu, Xe, Au) and deformed (Cu2, Xe2, Au2) versions are provided, where both versions have the same nuclear radius and surface thickness. There is no consensus on the uranium Woods-Saxon parameters, so three commonly used sets are provided:

The U and U2 sets are given in this recent overview of particle production from PHENIX. All other Woods-Saxon parameters (including U3) and the Hulthén wavefunction parameters are from the PHOBOS Glauber model.

For Woods-Saxon nuclei, trento can impose a minimum nucleon-nucleon distance. See the nucleon-min-dist option.

In addition, trento can read Arbitrary nuclear configurations saved in HDF5 files.

General options¶

These are general options that don’t fit in any other category.

-h, --help

Show the help message and exit.

--version

Print version number and exit.

--bibtex

Print bibtex entry and exit.

-c, --config-file FILE

Path to configuration file (see Configuration files below). May be given multiple times.

Output options¶

The default output mode is to print event-by-event properties to stdout, in the following order:

event_number impact_param npart mult e2 e3 e4 e5

with one line for each event, where

• event_number is an integer counter,

• impact_param is the collision impact parameter [fm],

• npart is the number of nucleon participants,

• mult is the integrated reduced thickness, and

• the en are the eccentricity harmonics ɛ_n.

This format is designed for easy parsing, redirection to files, etc. The output may be disabled with the -q/--quiet option.

Optionally, enabling --ncoll will also calculate the binary collision number ncoll for each event, and add it to the list of event-by-event properties sent to stdout:

event_number impact_param npart ncoll mult e2 e3 e4 e5

It also adds the ncoll attribute to both text and hdf5 output files. It’s worth noting that the code will run noticeably faster with --ncoll disabled, as it can skip checking pairwise collisions between nucleons which have already been struck.

By default, the actual initial density profiles (grids) are not output. There are two available output formats: text and HDF5 (if compiled).

In text mode, each event is written to a separate text file as a standard block-style grid, along with a commented header containing the event properties, like this:

# event 0
# b     = 2.964077155
# npart = 380
# mult  = 168.603282
# e2    = 0.01953253866
# e3    = 0.08961920965
# e4    = 0.1101683349
# e5    = 0.1727159106

The header may be disabled with the --no-header option.

HDF5 is a high-performance, cross-platform binary format for large numerical datasets. Libraries are available in most languages. HDF5 is significantly faster than text output: writing an event to a text file usually takes much longer than computing the actual event; writing to HDF5 incurs only a small overhead. Therefore, HDF5 is the recommended output format.

In HDF5 mode, all events are written to a single file with each event in a separate HDF5 dataset. Event properties are written to each dataset as HDF5 attributes with names b, npart, mult, e2, etc.

-q, --quiet

Disable printing event properties to stdout. Since both text and HDF5 output contain the event properties, it’s often desirable to specify this option along with the output option.

-o, --output PATH

Path to output events. If the path has an HDF5-like extension (.hdf5, .hdf, .hd5, .h5), then all events will be written to that HDF5 file. Otherwise, the path is interpreted as a directory and events will be written to numbered text files in the directory.

For text output, the directory will be created if it does not exist. If it does already exist, it must be empty (this is to avoid accidentally overwriting files or spewing thousands of files into an already-used location).

For HDF5 output, the file must not already exist. Each event will be written as a numbered dataset in the file, and the standard event properties will be written as dataset attributes.

Example:

• --output events will write to text files events/0.dat, events/1.dat, …

• --output events.hdf will write to HDF5 file events.hdf with dataset names event_0, event_1, …

--no-header

Disable writing event headers to text files.

Physical options¶

These options control the physical behavior of the model.

-p, --reduced-thickness FLOAT

Reduced thickness parameter p. The reduced thickness is defined as the generalized mean of participant nuclear thickness

\[T_R(p; T_A, T_B) = \biggl( \frac{T_A^p + T_B^p}{2} \biggr)^{1/p}\]

The default is p = 0, which corresponds to the geometric mean.

-k, --fluctuation FLOAT

Gamma distribution shape parameter k for nucleon fluctuations. Fluctuations are implemented by multiplying the density of each nucleon (or nucleon constituent) by a random weight. The weights are sampled from a gamma distribution with the scale parameter fixed so that the mean is one:

\[P_k(x) = \frac{k^k}{\Gamma(k)} x^{k-1} e^{-kx}\]

The default is k = 1, which corresponds to an exponential distribution. For small k, the distribution has a long tail, leading to large fluctuations. For large k, the distribution becomes a narrow Gaussian, and eventually a delta function for very large values.

-w, --nucleon-width FLOAT

Gaussian nucleon width in fm:

\[T_\text{nucleon}(x, y) = \frac{1}{2\pi w^2} \exp\biggl( -\frac{x^2 + y^2}{2w^2} \biggr)\]

The default is 0.5 fm. If nucleon substructure is enabled (see below), the parameter -w specifies the ensemble-averaged Gaussian nucleon width.

-v, --constit-width FLOAT

Gaussian constituent width in fm:

\[T_\text{constit}(x, y) = \frac{1}{2\pi v^2} \exp\biggl( -\frac{x^2 + y^2}{2v^2} \biggr)\]

By default, the constituent width is set equal to the nucleon width. It can take any positive real value, but it must not be set larger than the nucleon width.

New in version 2.0.

-m, --constit-number INT

Number of constituents inside the nucleon. The default is m=1, which means the nucleon is a single Gaussian (no substructure). Setting the constituent number m > 1 divides the nucleon into m Gaussians, each of width v. The constituent positions are sampled from the probability distribution

\[P(x, y) = \frac{1}{2\pi r^2} \exp\biggl[ -\frac{(x - x')^2 + (y - y')^2}{2r^2} \biggr],\]

where \((x', y')\) is the transverse position of the parent nucleon, and \(r\) is a constituent dispersion width, equal to

\[r = \sqrt{\frac{w^2 - v^2}{1 - 1/m}}.\]

Once sampled, the constituent positions are recentered so their centers of mass coincide with the presampled nucleon position \((x', y')\). Averaged over many samples, this procedure recovers a single Gaussian of width \(w\) as desired.

New in version 2.0.

-d, --nucleon-min-dist FLOAT

Minimum nucleon-nucleon distance (fm) for Woods-Saxon nuclei (spherical and deformed). When nonzero, if a sampled nucleon lands too close to a previously sampled nucleon, its angular position is resampled until it lands far enough away. The radius is not resampled, since this would effectively modify the Woods-Saxon distribution.

If a nucleon cannot be placed after a reasonable number of retries, the algorithm gives up and leaves the nucleon at the last sampled position. The failure rate is negligible for minimum distances of ~1 fm and below; it reaches roughly 1% at 1.7 fm for spherical nuclei and 1.5 fm for deformed.

The default is zero (no minimum distance).

New in version 1.4.

-x, --cross-section FLOAT

Inelastic nucleon-nucleon cross section σ_NN in fm². The default is 6.4 fm², the approximate experimental value at LHC Pb+Pb energy, √s = 2.76 TeV. Here are some measurements of the cross section at common beam energies (all have approximately 0.5 fm² uncertainty):

√s [TeV]	σNN [fm2]	ref.
0.200	4.23	1509.06727
2.76	6.4	1108.6027
	6.28	1208.4968
5.02	7.0	1210.3615
7	7.32	1208.4968

-n, --normalization FLOAT

Overall normalization factor. The default is 1.

--b-min FLOAT

Minimum impact parameter. The default is zero.

--b-max FLOAT

Maximum impact parameter. The default is to run minimum-bias collisions for the given collision system.

To run at fixed impact parameter, give the same value for both the min and the max.

--random-seed POSITIVE_INT

Primarily for testing and debugging.

Grid options¶

The thickness functions are discretized onto a square N × N grid centered at (0, 0). The grid can have a dramatic effect on code speed and precision, so should be set carefully. Computation time is roughly proportional to the number of grid cells (i.e. N²).

--grid-max FLOAT

x and y maximum of the grid in fm, i.e. the grid extends from -max to +max. The default is 10 fm, large enough to accommodate all collision systems. However, this should be set as small as possible, since an unnecessarily large grid slows down the code. For anything but uranium-uranium, 9 fm is sufficient. For pp and pA, 3 fm is usually a good choice.

--grid-step FLOAT

Size of grid cell in fm. The default is 0.2 fm, sufficient to achieve ~99.9% precision for the event properties. This can reasonably be increased as far as the nucleon (or constituent) width; beyond that and precision suffers significantly.

The grid will always be a square N × N array, with N = ceil(2*max/step). So e.g. the default settings (max = 10 fm, step = 0.2 fm) imply a 100 × 100 grid. The ceiling function ensures that the number of steps is always rounded up, so e.g. given max = 10 fm and step 0.3 fm, the grid will be 67 × 67. In this case, the actual grid max will be marginally increased (max = nsteps*step/2).

Regardless of the collision system, the code will always approximately center the overlap region on the grid.

Configuration files¶

All options may be saved in configuration files and passed to the program via the -c, --config-file option. Config files follow a simple key = value syntax, and lines beginning with a # are comments. The key for each option is its long option without the -- prefix. Here’s an example including all options:

# specify the projectile option twice
projectile = Pb
projectile = Pb
number-events = 1000

# don't print event properties to stdout, save to HDF5
quiet = true
output = PbPb.hdf

reduced-thickness = 0
fluctuation = 1
nucleon-width = 0.5
cross-section = 6.4
normalization = 1

# leave commented out for min-bias
# b-min =
# b-max =

grid-max = 10
grid-step = 0.2

Multiple config files can be given and they will be merged, so options can be separated into modular groups. For example, one could have a file common.conf containing settings for all collision systems and files PbPb.conf and pp.conf for specific collision systems:

# common.conf
reduced-thickness = 0.2
fluctuation = 1.5
nucleon-width = 0.6

# PbPb.conf
projectile = Pb
projectile = Pb
number-events = 10000
grid-max = 9

# pp.conf
projectile = p
projectile = p
number-events = 100000
grid-max = 3

To be used like so:

trento -c common.conf -c PbPb.conf
trento -c common.conf -c pp.conf

If an option is specified in a config file and on the command line, the command line overrides.

Arbitrary nuclear configurations¶

trento can read pre-generated nuclear configurations from HDF5 files.

The following files were created from publicly available data and can be input directly to trento. They are redistributed with permission from the authors.

• ³He configurations are from the PHOBOS Glauber model, created by Joe Carlson at LANL (ref).

• ²⁰⁸Pb configurations including realistic nucleon-nucleon correlations were created by Massimiliano Alvioli (ref 1, ref 2) and are available on his website.

If you use these configurations in your research, please cite the original authors.

To use pre-generated configurations, specify a path to an appropriate file on the command line in place of a species abbreviation:

trento path/to/file1.hdf path/to/file2.hdf

Filenames must have an HDF5-like extension (.hdf5, .hdf, .hd5, .h5). The files may be the same or different and may be mixed with standard species abbreviations. For each event, trento will choose a random configuration from the file and apply a random three-dimensional rotation. Hence, it is safe to run several events per pre-generated configuration.

For example, to run ³He+Au events at RHIC, download He3.hdf and execute

trento --cross-section 4.2 He3.hdf Au2

Remember to set the appropriate cross section for the desired beam energy!

To run custom configurations, make an HDF5 file containing a single dataset of shape (number_configs, number_nucleons, 3), where the first dimension corresponds to each configuration, the second dimension to each nucleon, and the third dimension to the (x, y, z) coordinates of each nucleon. Note that trento will read the file as single-precision floats, not doubles.

The easiest way to write an HDF5 file is with h5py:

import numpy as np
import h5py

# generate random data for 10 configs of a nucleus with 100 nucleons
configs = np.random.uniform(-1, 1, (10, 100, 3))

with h5py.File('nuclear_configs.hdf') as f:
   # the name of the dataset does not matter as long as there is only one
   f.create_dataset('configs', data=configs, dtype=np.float32)