[ALICE3] TRK: phiOffset column for the ML layers in the config file

The TRK configuration file (TRKBase.configFile) accepts an optional 9th column, phiOffset
(degrees, counterclockwise as phi), which rotates all the staves of a ML layer about the beam
axis, keeping their tilt. Existing files and the default layouts give the same geometry as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: lorber98

Detectors/Upgrades/ALICE3/TRKFT3/TRK/README.md

@@ -68,8 +68,9 @@ Both layouts use the same configuration-file syntax (only the OT geometry implem
 
 **Middle Layers (ML) - Indices 0 to 4**
 The first 5 valid lines are parsed as `TRKMLLayer` objects. These layers **require** a 6th parameter for the staggering offset (`stagOffset`).
-* **Format:** `rInn` \t `thick` \t `tiltAngle` \t `nStaves` \t `nMods` \t `stagOffset` \t `[optional_mode]` \t `[optional_rInnRow]`
+* **Format:** `rInn` \t `thick` \t `tiltAngle` \t `nStaves` \t `nMods` \t `stagOffset` \t `[optional_mode]` \t `[optional_rInnRow]` \t `[optional_phiOffset]`
 * Layers 3 and 4 are staggered: one stave out of two sits at `rInn`, the others are shifted by `stagOffset`. By default the even staves (stave 0 at phi = 0) are at `rInn`; `rInnRow` = 1 puts the odd staves there instead, i.e. stave 0 in the shifted row. In the flipped layer 3 the `rInn` row is the outer one and the shift points inwards, so there `rInnRow` = 1 puts stave 0 in the inner row; in layer 4 in the outer row. To give `rInnRow`, the mode column must be written too.
+* Stave `s` of a layer with `nStaves` = N is centred at phi = 360° · s / N (+ half a pitch if N is a multiple of 4), with stave 0 at phi = 0. `phiOffset` (degrees, counterclockwise as phi, default 0) rotates the whole layer about the beam axis: every stave is moved to phi + `phiOffset` and keeps its tilt with respect to its own radial direction. To give `phiOffset`, the mode and `rInnRow` columns must be written too.
 
 **Outer Layers (OT) - Indices 5 and above**
 From the 6th valid line onwards, lines are parsed as OT layer objects (`TRKOTLayer` for `kSegmented`, `TRKOTLayerRealistic` for `kSimplifiedRealistic`). These layers do **not** have a staggering offset. The optional mode parameter shifts to the 6th column.

Detectors/Upgrades/ALICE3/TRKFT3/TRK/simulation/include/TRKSimulation/TRKLayer.h

@@ -111,7 +111,7 @@ class TRKMLLayer : public TRKSegmentedLayer
 {
  public:
   TRKMLLayer() = default;
-  TRKMLLayer(int layerNumber, std::string layerName, float rInn, float staggerOffset, float tiltAngle, int numberOfStaves, int numberOfModules, float thickOrX2X0, MatBudgetParamMode mode, int rInnRow = 0);
+  TRKMLLayer(int layerNumber, std::string layerName, float rInn, float staggerOffset, float tiltAngle, int numberOfStaves, int numberOfModules, float thickOrX2X0, MatBudgetParamMode mode, int rInnRow = 0, float phiOffset = 0.f);
   ~TRKMLLayer() override = default;
 
   TGeoVolume* createStave() override;
@@ -122,6 +122,7 @@ class TRKMLLayer : public TRKSegmentedLayer
 
   float mStaggerOffset;
   int mRInnRow = 0; // staggered layers: staves with iStave % 2 == mRInnRow sit at rInn, the others are shifted by the stagger offset
+  float mPhiOffset = 0.f; // deg, rotation of all the staves of the layer about the beam axis (counterclockwise, as phi)
 
   static constexpr double sStaveWidth = constants::ML::width;
   static constexpr int sFlippedLayerNumber = 3;

Detectors/Upgrades/ALICE3/TRKFT3/TRK/simulation/src/Detector.cxx

@@ -227,6 +227,8 @@ void Detector::configFromFile(std::string fileName)
         // tmpBuff[6] = matBudgetMode (optional, default = Thickness)
         // tmpBuff[7] = rInnRow (optional, ML only, default = 0): which staves of a staggered layer sit at
         //              rInn, 0 = even, 1 = odd (needs tmpBuff[6]); in the flipped layer the rInn row is the outer one
+        // tmpBuff[8] = phiOffset (optional, ML only, default = 0): rotation of all the staves of the layer about
+        //              the beam axis, in degrees, counterclockwise as phi (needs tmpBuff[6] and tmpBuff[7])
 
         // Base parameters for all segmented layers (at least 5 needed)
         if (tmpBuff.size() < 5) {
@@ -253,8 +255,9 @@ void Detector::configFromFile(std::string fileName)
             matBudgetMode = static_cast<MatBudgetParamMode>(static_cast<int>(tmpBuff[6]));
           }
           const int rInnRow = (tmpBuff.size() >= 8) ? static_cast<int>(tmpBuff[7]) : 0;
+          const float phiOffset = (tmpBuff.size() >= 9) ? tmpBuff[8] : 0.f;
 
-          mLayers.push_back(std::make_unique<TRKMLLayer>(layerCount, name, rInn, stagOffset, tiltAngle, nStaves, nMods, thick, matBudgetMode, rInnRow));
+          mLayers.push_back(std::make_unique<TRKMLLayer>(layerCount, name, rInn, stagOffset, tiltAngle, nStaves, nMods, thick, matBudgetMode, rInnRow, phiOffset));
         } else {
           // OT layers do NOT have stagOffset. The optional mode is at index 5.
           if (tmpBuff.size() >= 6) {

Detectors/Upgrades/ALICE3/TRKFT3/TRK/simulation/src/TRKLayer.cxx

@@ -233,9 +233,12 @@ std::pair<float, float> TRKSegmentedLayer::getBoundingRadii(double staveWidth) c
 
 /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
-TRKMLLayer::TRKMLLayer(int layerNumber, std::string layerName, float rInn, float staggerOffset, float tiltAngle, int numberOfStaves, int numberOfModules, float thickOrX2X0, MatBudgetParamMode mode, int rInnRow)
-  : TRKSegmentedLayer(layerNumber, layerName, rInn, tiltAngle, numberOfStaves, numberOfModules, thickOrX2X0, mode), mStaggerOffset(staggerOffset), mRInnRow(rInnRow)
+TRKMLLayer::TRKMLLayer(int layerNumber, std::string layerName, float rInn, float staggerOffset, float tiltAngle, int numberOfStaves, int numberOfModules, float thickOrX2X0, MatBudgetParamMode mode, int rInnRow, float phiOffset)
+  : TRKSegmentedLayer(layerNumber, layerName, rInn, tiltAngle, numberOfStaves, numberOfModules, thickOrX2X0, mode), mStaggerOffset(staggerOffset), mRInnRow(rInnRow), mPhiOffset(phiOffset)
 {
+  if (mPhiOffset != 0.f) {
+    LOGP(info, "Layer {}: staves rotated by {} deg about the beam axis (phiOffset)", mLayerNumber, mPhiOffset);
+  }
   if (mLayerNumber == sFlippedLayerNumber) {
     mOuterRadius = rInn;
     mInnerRadius = rInn - mChipThickness;
@@ -348,8 +351,9 @@ void TRKMLLayer::createLayer(TGeoVolume* motherVolume)
   for (int iStave = 0; iStave < mNumberOfStaves; iStave++) {
     TGeoVolume* staveVol = createStave();
     TGeoCombiTrans* trans = new TGeoCombiTrans();
-    // If the number of staves is a multiple of 4, rotate by half a stave to avoid having the first one exactly on the x
-    double phi = (mNumberOfStaves % 4 == 0) ? theta * (iStave + 0.5) : theta * iStave;
+    // If the number of staves is a multiple of 4, rotate by half a stave to avoid having the first one exactly on the x;
+    // mPhiOffset rotates the whole layer (position and orientation of every stave) about the beam axis
+    double phi = ((mNumberOfStaves % 4 == 0) ? theta * (iStave + 0.5) : theta * iStave) + mPhiOffset * TMath::DegToRad();
     double phiDeg = phi * TMath::RadToDeg();
     TGeoRotation* rot = new TGeoRotation("rot", phiDeg + 90 + mTiltAngle, 0, 0);
     trans->SetRotation(rot);