Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions DataFormats/simulation/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,11 @@ o2_add_test(MCCompLabel
COMPONENT_NAME SimulationDataFormat
PUBLIC_LINK_LIBRARIES O2::SimulationDataFormat)

o2_add_test(O2DatabasePDG
SOURCES test/testO2DatabasePDG.cxx
COMPONENT_NAME SimulationDataFormat
PUBLIC_LINK_LIBRARIES O2::SimulationDataFormat)

o2_add_test(MCEventLabel
SOURCES test/testMCEventLabel.cxx
COMPONENT_NAME SimulationDataFormat
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -86,20 +86,85 @@ class O2DatabasePDG
return particle->Mass();
}

// Returns true for the PDG codes that Pythia8/Angantyr gives to its nucleus remnants.
// NOTE: this is a test on the shape of the code, not proof of its origin. Geant4 uses the
// same I = 9 slot for an excited ion whose level index it does not know (G4IonTable::
// GetNucleusEncoding adds 9 when the excitation energy is non-zero and the level is not in
// 1..9), so transport can hand us codes that match this test and are not remnants at all.
// That is why Mass() below only uses the remnant formula once the database has nothing for
// the code and nothing for its ground state, and why L = 0 is required here: the formula
// counts nucleons only, so it would miss the Lambda mass of a hypernucleus entirely.
static bool isNucleusRemnantCode(int pdg)
{
const int abspdg = pdg < 0 ? -pdg : pdg;
return abspdg >= IONBASELOW && abspdg <= IONBASEHIGH && abspdg % 10 == 9 &&
(abspdg / 10000000) % 10 == 0;
}

// Z and A encoded in a +-10LZZZAAA9 nucleus remnant code; both 0 for any other code
static void nucleusRemnantZA(int pdg, int& Z, int& A)
{
Z = A = 0;
if (!isNucleusRemnantCode(pdg)) {
return;
}
const int code = (pdg < 0 ? -pdg : pdg) / 10;
A = code % 1000;
Z = (code / 1000) % 1000;
}

// Mass in GeV of a nucleus remnant as the sum of the free nucleon masses, Z * m_p +
// (A - Z) * m_n; -1 if pdg is not a remnant code or the nucleon masses are unavailable.
// For anything that does have a ground state, Mass() prefers that ground state, which also accounts for the
// binding energy this sum ignores: Angantyr gives its remnant the mass A * m_beam/A_beam
// (the spectator nucleons keep the effective, bound nucleon mass of the beam, measured as
// 11.17438 GeV for a Z=6, A=12 remnant of an O-16 beam), so this sum sits about 0.8 %
// high. Where the table does have a ground state it is the closer of the two, which is
// why Mass() prefers it.
static Double_t nucleusRemnantMass(int pdg, TDatabasePDG* db = O2DatabasePDG::Instance())
{
int Z = 0, A = 0;
nucleusRemnantZA(pdg, Z, A);
if (A < 1 || Z > A) {
return -1.;
}
const auto proton = db->GetParticle(2212);
const auto neutron = db->GetParticle(2112);
if (proton == nullptr || neutron == nullptr) {
return -1.;
}
return Z * proton->Mass() + (A - Z) * neutron->Mass();
}

// determine particle to get mass for based on PDG
static Double_t Mass(int pdg, bool& success, TDatabasePDG* db = O2DatabasePDG::Instance())
{
if (pdg < IONBASELOW || pdg > IONBASEHIGH) {
// not an ion, return immediately
return MassImpl(db->GetParticle(pdg), success);
}
// giving priority here to value held in the database
if (auto particle = db->GetParticle(pdg)) {
// see if this ion can be found
return MassImpl(particle, success);
}
// if we are here, try one last time to look for ground state of potential isomere state
pdg = pdg / 10 * 10;
return MassImpl(db->GetParticle(pdg), success);
const int abspdg = pdg < 0 ? -pdg : pdg;
if (abspdg < IONBASELOW || abspdg > IONBASEHIGH) {
// not an ion, and not in the database
return MassImpl(nullptr, success);
}
// an ion: try the ground state of a potential isomere state. The lookup goes through
// |pdg| so that an anti-nucleus gets the mass of its nucleus instead of -1, which is
// what it used to get.
if (auto particle = db->GetParticle(abspdg / 10 * 10)) {
return MassImpl(particle, success);
}
// Nothing in the table for the code or its ground state. If it looks like a Pythia8/
// Angantyr nucleus remnant, fall back to deriving the mass from the code itself. Only
// this last step is formula based, and it has to be: these codes are never added to
// TDatabasePDG (see the comment in GeneratorPythia8::importParticles -- the table is
// process wide and ROOT does not lock it, so writing to it while events are being
// generated would race with the readers), so no lookup can ever resolve them.
if (const auto mass = nucleusRemnantMass(pdg, db); mass > 0.) {
success = true;
return mass;
}
return MassImpl(nullptr, success);
}

// remove default constructor
Expand Down
109 changes: 109 additions & 0 deletions DataFormats/simulation/test/testO2DatabasePDG.cxx
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
// Copyright 2019-2026 CERN and copyright holders of ALICE O2.
// See https://alice-o2.web.cern.ch/copyright for details of the copyright holders.
// All rights not expressly granted are reserved.
//
// This software is distributed under the terms of the GNU General Public
// License v3 (GPL Version 3), copied verbatim in the file "COPYING".
//
// In applying this license CERN does not waive the privileges and immunities
// granted to it by virtue of its status as an Intergovernmental Organization
// or submit itself to any jurisdiction.
/// @author Marco Giacalone
/// co-authored by Claude Opus 5.5
/// @date 11-2026

#define BOOST_TEST_MODULE Test O2DatabasePDG
#define BOOST_TEST_MAIN
#define BOOST_TEST_DYN_LINK
#include <boost/test/unit_test.hpp>
#include "SimulationDataFormat/O2DatabasePDG.h"

using namespace o2;

// The nucleus remnant codes below are the ones Pythia8/Angantyr produces for heavy-ion runs:
// +-10LZZZAAA9, one lump per beam holding all the spectator nucleons of that beam.
BOOST_AUTO_TEST_CASE(NucleusRemnantCode_test)
{
// shape of the code, both signs
BOOST_CHECK(O2DatabasePDG::isNucleusRemnantCode(1000040089));
BOOST_CHECK(O2DatabasePDG::isNucleusRemnantCode(-1000040089));
BOOST_CHECK(O2DatabasePDG::isNucleusRemnantCode(1000822089));
// ground states and other isomer levels are not remnants
BOOST_CHECK(!O2DatabasePDG::isNucleusRemnantCode(1000040080));
BOOST_CHECK(!O2DatabasePDG::isNucleusRemnantCode(1000040081));
// a hypernucleus is not a remnant: Angantyr remnants carry no strangeness, and the mass
// formula counts nucleons only, so it would miss the Lambda mass
BOOST_CHECK(!O2DatabasePDG::isNucleusRemnantCode(1010010039));
// not ions at all
BOOST_CHECK(!O2DatabasePDG::isNucleusRemnantCode(211));
BOOST_CHECK(!O2DatabasePDG::isNucleusRemnantCode(-211));
BOOST_CHECK(!O2DatabasePDG::isNucleusRemnantCode(1100000009));

int Z = -1, A = -1;
O2DatabasePDG::nucleusRemnantZA(1000822089, Z, A);
BOOST_CHECK_EQUAL(Z, 82);
BOOST_CHECK_EQUAL(A, 208);
O2DatabasePDG::nucleusRemnantZA(-1000000029, Z, A);
BOOST_CHECK_EQUAL(Z, 0);
BOOST_CHECK_EQUAL(A, 2);
O2DatabasePDG::nucleusRemnantZA(211, Z, A);
BOOST_CHECK_EQUAL(Z, 0);
BOOST_CHECK_EQUAL(A, 0);
}

BOOST_AUTO_TEST_CASE(Mass_test)
{
auto db = O2DatabasePDG::Instance();
const double mp = db->GetParticle(2212)->Mass();
const double mn = db->GetParticle(2112)->Mass();
const double tolerance = 1.e-9;
bool success = false;

// ordinary particles and ions are looked up by their exact code
BOOST_CHECK_CLOSE(O2DatabasePDG::Mass(211, success), db->GetParticle(211)->Mass(), tolerance);
BOOST_CHECK(success);
BOOST_CHECK_CLOSE(O2DatabasePDG::Mass(1000020030, success), db->GetParticle(1000020030)->Mass(), tolerance);
BOOST_CHECK(success);

// an isomere state falls back to its ground state
BOOST_CHECK_CLOSE(O2DatabasePDG::Mass(1000020031, success), db->GetParticle(1000020030)->Mass(), tolerance);
BOOST_CHECK(success);

// so does an excited ion that Geant4 encoded with an unknown level (isomer digit 9)
BOOST_CHECK_CLOSE(O2DatabasePDG::Mass(1000020049, success), db->GetParticle(1000020040)->Mass(), tolerance);
BOOST_CHECK(success);

// and so does a hypernucleus with that digit: the remnant formula would be short of the
// Lambda mass, which is why isNucleusRemnantCode() requires L = 0
BOOST_CHECK_CLOSE(O2DatabasePDG::Mass(1010010039, success), db->GetParticle(1010010030)->Mass(), tolerance);
BOOST_CHECK(success);

// a remnant whose ground state is known keeps that ground state mass, binding included
BOOST_CHECK_CLOSE(O2DatabasePDG::Mass(1000010029, success), db->GetParticle(1000010020)->Mass(), tolerance);
BOOST_CHECK(success);

// a remnant that is no nucleus at all has no ground state: Z * m_p + (A - Z) * m_n
BOOST_CHECK_CLOSE(O2DatabasePDG::Mass(1000000029, success), 2. * mn, tolerance);
BOOST_CHECK(success);
BOOST_CHECK_CLOSE(O2DatabasePDG::Mass(1000020029, success), 2. * mp, tolerance);
BOOST_CHECK(success);
BOOST_CHECK_CLOSE(O2DatabasePDG::Mass(1000010079, success), mp + 6. * mn, tolerance);
BOOST_CHECK(success);

// a nucleus and an anti-nucleus have the same mass, whichever branch they take
for (int pdg : {1000822089, 1000010029, 1000000029, 1000040089, 1000080169, 1000020030}) {
bool successAnti = false;
const auto mass = O2DatabasePDG::Mass(pdg, success);
const auto massAnti = O2DatabasePDG::Mass(-pdg, successAnti);
BOOST_CHECK(success);
BOOST_CHECK(successAnti);
BOOST_CHECK_CLOSE(mass, massAnti, tolerance);
}

// unknown codes still fail, they do not get an invented mass
BOOST_CHECK(O2DatabasePDG::Mass(99999999, success) < 0.);
BOOST_CHECK(!success);
BOOST_CHECK(O2DatabasePDG::Mass(1000990081, success) < 0.);
BOOST_CHECK(!success);
BOOST_CHECK(O2DatabasePDG::nucleusRemnantMass(211) < 0.);
}
37 changes: 21 additions & 16 deletions Generators/src/GeneratorPythia8.cxx
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
#include "SimulationDataFormat/MCEventHeader.h"
#include "SimulationDataFormat/MCGenProperties.h"
#include "SimulationDataFormat/ParticleStatus.h"
#include "SimulationDataFormat/O2DatabasePDG.h"
#if PYTHIA_VERSION_INTEGER >= 8310
#include "Pythia8/HIInfo.h"
#else
Expand Down Expand Up @@ -660,6 +661,15 @@
// first particle is system
auto particle = event[iparticle];
auto pdg = particle.id();
// Pythia8/Angantyr adds one nucleus remnant per beam (Angantyr::addNucleusRemnants): a
// single lump with PDG code +-10LZZZAAA9 holding all the non-interacting nucleons, known
// to Pythia particle table only. These codes are deliberately not added to TDatabasePDG:
// importParticles() runs in a TBB worker thread under GeneratorHybrid, while other threads
// read the same process-wide table (TParticle's constructor, PrimaryGenerator::AddTrack),
// and ROOT locks neither side. Given that those nuclei haven't been transported until now,

Check failure on line 669 in Generators/src/GeneratorPythia8.cxx

View workflow job for this annotation

GitHub Actions / PR formatting / whitespace

Trailing spaces

Remove the trailing spaces at the end of the line.
// they are set as "not to be tracked", which disables directly the warning.
// This behaviour could change in the future, if we decide to add the remnant codes to TDatabasePDG.
const bool isRemnant = O2DatabasePDG::isNucleusRemnantCode(pdg);
auto st = o2::mcgenstatus::MCGenStatusEncoding(particle.statusHepMC(), //
particle.status()) //
.fullEncoding;
Expand All @@ -677,8 +687,9 @@
particle.yProd(), // Production Y
particle.zProd(), // Production Z
particle.tProd())); // Production t
mParticles.back().SetBit(ParticleStatus::kToBeDone, //
particle.statusHepMC() == 1);
// nucleus remnants are spectators: they are final state, but they are never transported
mParticles.back().SetBit(ParticleStatus::kToBeDone, //
particle.statusHepMC() == 1 && !isRemnant);
}

/** success **/
Expand Down Expand Up @@ -982,24 +993,18 @@
auto nparticles = event.size();
for (int ipa = 0; ipa < nparticles; ++ipa) {
const auto particle = event[ipa];
auto pdg = particle.id();
const auto pdg = particle.id();

// nuclear remnants have pdg code = ±10LZZZAAA9
if (pdg < 1000000000) {
continue; // must be nucleus
}
if (pdg % 10 != 9) {
continue; // first digit must be 9
// nuclear remnants have pdg code = 10LZZZAAA9. As before, only the positive codes are
// counted: the projectile/target assignment below goes by the sign of pz, so remnants of
// an anti-nucleus beam would be reported as if they were nuclei.
if (pdg < 0 || !O2DatabasePDG::isNucleusRemnantCode(pdg)) {
continue;
}
nNucRem++;

// extract A, Z and L from pdg code
pdg /= 10;
auto A = pdg % 1000;
pdg /= 1000;
auto Z = pdg % 1000;
pdg /= 1000;
auto L = pdg % 10;
int Z = 0, A = 0;
O2DatabasePDG::nucleusRemnantZA(pdg, Z, A);

if (particle.pz() > 0.) {
nProtonProj = Z;
Expand Down
Loading