[ntuple] add SoA tutorial

Author: jblomer

tutorials/io/ntuple/ntpl020_soa.C

@@ -0,0 +1,127 @@
+/// \file
+/// \ingroup tutorial_ntuple
+/// \notebook
+/// Example of RNTuple I/O on collections with a SoA memory layout
+///
+/// RNTuple on-disk collections can be used in struct-of-arrays (SoA) memory layout.
+/// An RNTuple SoA class consists of persistent members of type `RVec` corresponding to
+/// and underlying record type, as shown in this tutorial.
+///
+/// NOTE: The RNTuple SoA I/O is still experimental at this point.
+/// Functionality and interface are subject to changes.
+///
+/// \macro_code
+///
+/// \date April 2026
+/// \author The ROOT Team
+
+#include <ROOT/REntry.hxx>
+#include <ROOT/RNTupleModel.hxx>
+#include <ROOT/RNTupleReader.hxx>
+#include <ROOT/RNTupleWriter.hxx>
+#include <ROOT/RVec.hxx>
+
+#include <TCanvas.h>
+#include <TClass.h>
+#include <TDictAttributeMap.h>
+#include <TEllipse.h>
+#include <TGraph.h>
+#include <TRandom.h>
+
+#include <iostream>
+#include <memory>
+
+constexpr const char *kFileName = "ntpl020_soa.root";
+constexpr const char *kNTupleName = "ntpl";
+constexpr unsigned int kNPoints = 10000;
+
+// The SoA class for this tutorial. Contains a number of 2D points. All vectors have to have the same length.
+// Note that RVecs can adopt memory.
+struct PointSoA {
+   ROOT::RVec<float> fX;
+   ROOT::RVec<float> fY;
+};
+
+// The underlying record type for the SoA class. Members between the SoA class and the underlying record type
+// are matched by name. Every member of type `T` in the underlying record type has to be of type `ROOT::RVec<T>` in
+// the SoA class.
+struct PointRecord {
+   float fX;
+   float fY;
+};
+
+void Write()
+{
+   // We will use our own memory are to store the points
+   auto memory = std::make_unique<float[]>(kNPoints * 2);
+
+   // Create random points in the unit square
+   gRandom->RndmArray(2 * kNPoints, memory.get());
+
+   // Adopt the memory by a PointSoA object. First all x values, then all y values.
+   PointSoA points{ROOT::RVec<float>(memory.get(), kNPoints),
+                   ROOT::RVec<float>(memory.get() + kNPoints, kNPoints)};
+
+   // Create a model with a SoA field
+   auto model = ROOT::RNTupleModel::CreateBare();
+   model->AddField(ROOT::RFieldBase::Create("points", "PointSoA").Unwrap());
+
+   // Write a single entry with the points
+   auto writer = ROOT::RNTupleWriter::Recreate(std::move(model), kNTupleName, kFileName);
+   auto entry = writer->GetModel().CreateBareEntry();
+   entry->BindRawPtr("points", &points);
+   writer->Fill(*entry);
+}
+
+void Read()
+{
+   auto reader = ROOT::RNTupleReader::Open(kNTupleName, kFileName);
+
+   // Show on-disk layout: collection of underlying record type (AoS)
+   reader->PrintInfo();
+
+   // Read back the points in two steps: first get the size and then read into adopted RVecs.
+   auto viewSize = reader->GetCollectionView("points");
+   const auto N = viewSize(0); // size of the SoA collection of the first (and only) entry
+   auto memory = std::make_unique<float[]>(N * 2);
+
+   PointSoA points{ROOT::RVec<float>(memory.get(), N), ROOT::RVec<float>(memory.get() + N, N)};
+   auto viewSoA = reader->GetView("points", &points, "PointSoA");
+   viewSoA(0);
+
+   // Use the raw memory area to draw the points
+   auto c = new TCanvas("c", "", 1000, 1000);
+   auto *graph = new TGraph(N, &memory[0], &memory[N]);
+   graph->SetMarkerStyle(29);
+   graph->SetMarkerSize(1);
+   graph->SetMarkerColor(kRed);
+   graph->Draw("AP");
+   auto *circle = new TEllipse(0.5, 0.5, 0.5, 0.5);
+   circle->SetFillStyle(0);
+   circle->SetLineColor(kBlue);
+   circle->SetLineWidth(4);
+   circle->Draw();
+   c->Update();
+
+   // Use adopted RVec's to approximate PI
+   points.fX -= 0.5;
+   points.fY -= 0.5;
+   auto isInCircle = points.fX * points.fX + points.fY * points.fY < 0.25;
+   auto hits = ROOT::VecOps::Sum(isInCircle);
+   float approxPI = 4.0 * static_cast<float>(hits) / static_cast<float>(N);
+   std::cout << "Approximated PI to " << approxPI << std::endl;
+}
+
+void ntpl020_soa()
+{
+   // Usually, the SoA class dictionary definition would mark it as a SoA class of the corresponding
+   // underlying record type like this
+   //     #pragma link C++ options=rntupleSoARecord(PointRecord) class PointSoA+;
+   // For the interpreted classes in this tutorial, we mark the SoA class at runtime:
+   auto cl = TClass::GetClass("PointSoA");
+   cl->CreateAttributeMap();
+   cl->GetAttributeMap()->AddProperty("rntuple.SoARecord", "PointRecord");
+
+   Write();
+   Read();
+}