Possibility to globally bias MeanVertex objects via env.var

Following ITS realignment the mean vertex position may change.
To avoid recalibration of the huge amount of MeanVertex objects in the CCDB,
one can globally bias them via env.var O2_DPL_MVBIAS providing the
--configKeyValues-like string for the MeanVertexBiasParam
ConfigurableParam ("mvbias"). E.g.

export O2_DPL_MVBIAS="mvbias.xyz[0]=0.002;mvbias.xyz[1]=-0.12;mvbias.slopeY=0.0005"

will shift all loaded positions by 0.002 cm in X and -0.12 cm in y and increase the
y slope by 0.5mrad.
At the very first call of MeanVertex constructor the bias will be reported as:
root [0] o2::dataformats::MeanVertexObject mv;
[INFO] Mean vertex is biased by: XYZ: 0.0020,-0.1200,0.0000 SlopeXY: 0.000e+00,5.000e-04

Author: shahor02

DataFormats/Calibration/CMakeLists.txt

@@ -11,9 +11,12 @@
 
 o2_add_library(DataFormatsCalibration
                SOURCES src/MeanVertexObject.cxx
+               SOURCES src/MeanVertexBiasParam.cxx
                PUBLIC_LINK_LIBRARIES O2::ReconstructionDataFormats
-                                     O2::Framework)
+                                     O2::Framework
+                                     O2::CommonUtils)
 
 o2_target_root_dictionary(DataFormatsCalibration
-                          HEADERS include/DataFormatsCalibration/MeanVertexObject.h)
+                          HEADERS include/DataFormatsCalibration/MeanVertexObject.h
+                                  include/DataFormatsCalibration/MeanVertexBiasParam.h)
 

DataFormats/Calibration/include/DataFormatsCalibration/MeanVertexBiasParam.h

@@ -0,0 +1,38 @@
+// 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 ruben.shahoyan@cern.ch
+
+/// parameters to bias precalibrated mean vertex, e.g after the alignment shift
+
+#ifndef ALICEO2_MEANVERTEX_BIAS_PARAM_H
+#define ALICEO2_MEANVERTEX_BIAS_PARAM_H
+
+#include "CommonUtils/ConfigurableParam.h"
+#include "CommonUtils/ConfigurableParamHelper.h"
+
+namespace o2
+{
+namespace dataformats
+{
+
+struct MeanVertexBiasParam : public o2::conf::ConfigurableParamHelper<MeanVertexBiasParam> {
+  float xyz[3] = {};  // position bias
+  float slopeX = 0.f; // x slope bias
+  float slopeY = 0.f; // y slope bias
+
+  O2ParamDef(MeanVertexBiasParam, "mvbias");
+};
+
+} // namespace dataformats
+} // end namespace o2
+
+#endif

DataFormats/Calibration/include/DataFormatsCalibration/MeanVertexObject.h

@@ -15,31 +15,45 @@
 #include <array>
 #include "Framework/Logger.h"
 #include "ReconstructionDataFormats/Vertex.h"
+#include "DataFormatsCalibration/MeanVertexBiasParam.h"
 
 namespace o2
 {
 namespace dataformats
 {
 class MeanVertexObject : public VertexBase
 {
-
  public:
   MeanVertexObject(float x, float y, float z, float sigmax, float sigmay, float sigmaz, float slopeX, float slopeY)
   {
+    if (!gMVBias) {
+      checkExternalBias();
+    }
     setXYZ(x, y, z);
     setSigma({sigmax, sigmay, sigmaz});
     mSlopeX = slopeX;
     mSlopeY = slopeY;
   }
+
   MeanVertexObject(std::array<float, 3> pos, std::array<float, 3> sigma, float slopeX, float slopeY)
   {
+    if (!gMVBias) {
+      checkExternalBias();
+    }
     math_utils::Point3D<float> p(pos[0], pos[1], pos[2]);
     setPos(p);
     setSigma(sigma);
     mSlopeX = slopeX;
     mSlopeY = slopeY;
   }
-  MeanVertexObject() = default;
+
+  MeanVertexObject()
+  {
+    if (!gMVBias) {
+      checkExternalBias();
+    }
+  }
+
   ~MeanVertexObject() = default;
   MeanVertexObject(const MeanVertexObject& other) = default;
   MeanVertexObject(MeanVertexObject&& other) = default;
@@ -57,14 +71,28 @@ class MeanVertexObject : public VertexBase
   void setSlopeX(float val) { mSlopeX = val; }
   void setSlopeY(float val) { mSlopeY = val; }
 
-  math_utils::Point3D<float>& getPos() { return getXYZ(); }
+  // getting the cartesian coordinates and errors
+  float getX() const { return VertexBase::getX() + gMVBias->xyz[0]; }
+  float getY() const
+  {
+    return VertexBase::getY() + gMVBias->xyz[1];
+    ;
+  }
+  float getZ() const
+  {
+    return VertexBase::getZ() + gMVBias->xyz[2];
+    ;
+  }
+  float getR() const { return gpu::CAMath::Hypot(getX(), getY()); }
+
+  math_utils::Point3D<float> getXYZ() const { return {getX(), getY(), getZ()}; }
   math_utils::Point3D<float> getPos() const { return getXYZ(); }
 
-  float getSlopeX() const { return mSlopeX; }
-  float getSlopeY() const { return mSlopeY; }
+  float getSlopeX() const { return mSlopeX + gMVBias->slopeX; }
+  float getSlopeY() const { return mSlopeY + gMVBias->slopeY; }
 
-  float getXAtZ(float z) const { return getX() + mSlopeX * (z - getZ()); }
-  float getYAtZ(float z) const { return getY() + mSlopeY * (z - getZ()); }
+  float getXAtZ(float z) const { return getX() + getSlopeX() * (z - getZ()); }
+  float getYAtZ(float z) const { return getY() + getSlopeY() * (z - getZ()); }
 
   void print() const;
   std::string asString() const;
@@ -82,21 +110,24 @@ class MeanVertexObject : public VertexBase
 
   void setMeanXYVertexAtZ(VertexBase& v, float z) const
   {
-    float dz = z - getZ();
-    v.setX(getX() + mSlopeX * dz);
-    v.setY(getY() + mSlopeY * dz);
+    v.setX(getXAtZ(z));
+    v.setY(getYAtZ(z));
     v.setZ(z);
   }
 
-  const VertexBase& getMeanVertex() const
+  const VertexBase getMeanVertex() const
   {
-    return (const VertexBase&)(*this);
+    return getMeanVertex(getZ());
   }
 
+  static void checkExternalBias();
+
  private:
   float mSlopeX{0.f}; // slope of x = f(z)
   float mSlopeY{0.f}; // slope of y = f(z)
 
+  static const MeanVertexBiasParam* gMVBias;
+
   ClassDefNV(MeanVertexObject, 2);
 };
 

DataFormats/Calibration/src/DataFormatsCalibrationLinkDef.h

@@ -15,6 +15,8 @@
 #pragma link off all classes;
 #pragma link off all functions;
 
-#pragma link C++ struct o2::dataformats::MeanVertexObject + ;
+#pragma link C++ class o2::dataformats::MeanVertexObject + ;
+#pragma link C++ class o2::dataformats::MeanVertexBiasParam + ;
+#pragma link C++ class o2::conf::ConfigurableParamHelper < o2::dataformats::MeanVertexBiasParam> + ;
 
 #endif

DataFormats/Calibration/src/MeanVertexBiasParam.cxx

@@ -0,0 +1,18 @@
+// 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 ruben.shahoyan@cern.ch
+
+/// parameters to bias precalibrated mean vertex, e.g after the alignment shift
+
+#include "DataFormatsCalibration/MeanVertexBiasParam.h"
+
+O2ParamImpl(o2::dataformats::MeanVertexBiasParam);

DataFormats/Calibration/src/MeanVertexObject.cxx

@@ -12,10 +12,13 @@
 #include "DataFormatsCalibration/MeanVertexObject.h"
 #include "TRandom.h"
 
+#include <cstdlib>
+
 namespace o2
 {
 namespace dataformats
 {
+const MeanVertexBiasParam* MeanVertexObject::gMVBias = nullptr;
 
 void MeanVertexObject::set(int icoord, float val)
 {
@@ -45,7 +48,9 @@ void MeanVertexObject::setSigma(int icoord, float val)
 
 std::string MeanVertexObject::asString() const
 {
-  return VertexBase::asString() + fmt::format(" Slopes {{{:+.4e},{:+.4e}}}", mSlopeX, mSlopeY);
+  return fmt::format("Vtx {{{:+.4e},{:+.4e},{:+.4e}}} Cov.:{{{{{:.3e}..}},{{{:.3e},{:.3e}..}},{{{:.3e},{:.3e},{:.3e}}}}} | bias: XYZ: {:.4f},{:.4f},{:.4f} SlopeXY: {:.3e},{:.3e}",
+                     getX(), getY(), getZ(), mCov[0], mCov[1], mCov[2], mCov[3], mCov[4], mCov[5],
+                     gMVBias->xyz[0], gMVBias->xyz[1], gMVBias->xyz[2], gMVBias->slopeX, gMVBias->slopeY);
 }
 
 std::ostream& operator<<(std::ostream& os, const o2::dataformats::MeanVertexObject& o)
@@ -70,5 +75,16 @@ math_utils::Point3D<float> MeanVertexObject::sample() const
   return math_utils::Point3D<float>(x, y, z);
 }
 
+void MeanVertexObject::checkExternalBias()
+{
+  // posibility to globally bias all data members with the proper env.var
+  if (const auto* biasString = std::getenv("O2_DPL_MVBIAS"); biasString && *biasString) {
+    o2::conf::ConfigurableParam::updateFromString(biasString);
+  }
+  gMVBias = &MeanVertexBiasParam::Instance();
+  LOGP(info, "Mean vertex is biased by: XYZ: {:.4f},{:.4f},{:.4f} SlopeXY: {:.3e},{:.3e}",
+       gMVBias->xyz[0], gMVBias->xyz[1], gMVBias->xyz[2], gMVBias->slopeX, gMVBias->slopeY);
+}
+
 } // namespace dataformats
 } // namespace o2