feat: helicity correction function QADB::CorrectHelicitySign (#69)

src/clasqa/QADB.groovy

@@ -7,6 +7,10 @@ import clasqa.Tools
 
 class QADB {
 
+  final MISC_BIT       = 5 // FIXME: should be obtained from `defect_definitions.json`
+  final BSAWRONG_BIT   = 10
+  final BSAUNKNOWN_BIT = 11
+
   //..............
   // constructor
   //``````````````
@@ -264,9 +268,9 @@ class QADB {
       return false
     }
     def use_mask = mask
-    if(hasDefectBit(5)) {
+    if(hasDefectBit(MISC_BIT)) {
       if(runnum_ in allowMiscBitList) {
-        use_mask &= ~(0x1 << 5) // set `use_mask`'s Misc bit to 0
+        use_mask &= ~(0x1 << MISC_BIT) // set `use_mask`'s Misc bit to 0
       }
     }
     return foundHere && !(defect & use_mask)
@@ -471,6 +475,32 @@ class QADB {
   public void resetAccumulatedCharge() { chargeTotal = 0 }
 
 
+  //.................................
+  // Helicity Sign Correction
+  //`````````````````````````````````
+  // use this method to get the correct helicity sign:
+  // - this method returns -1 if the QA bin has the `BSAWrong` defect,
+  //   which indicates the helicity sign in the data is incorrect
+  // - therefore:
+  //   'true helicity' = 'helicity from data' * CorrectHelicitySign(run_number, event_number)
+  // - zero is returned, if the event is not found in the QADB or if the pion BSA
+  //   sign is not distinguishable from zero
+  // - the return value is constant for a run, but is still assigned per QA bin, for
+  //   full generality
+  // - the return value may NOT be constant for all runs in a data set; for example,
+  //   deviations from the normal value happen when a single run is cooked with the
+  //   wrong HWP position
+  public int correctHelicitySign(int runnum_, int evnum_) {
+    def foundHere = query(runnum_,evnum_)
+    if(!foundHere) {
+      return 0
+    }
+    if(hasDefectBit(BSAUNKNOWN_BIT)) {
+      return 0
+    }
+    return hasDefectBit(BSAWRONG_BIT) ? -1 : 1
+  }
+
 
   //===============================================================
 

src/tests/testCorrectHelicitySign.groovy

@@ -0,0 +1,14 @@
+import clasqa.QADB
+
+def runnum
+final EVNUM = 100000 // FIXME: assumption
+def cook
+if(args.length>=2) {
+  cook   = args[0]
+  runnum = args[1].toInteger()
+} else {
+  throw new Exception("arguments must be [cook] [runnum]")
+}
+
+QADB qa = new QADB(cook)
+System.out.println(qa.correctHelicitySign(runnum, EVNUM))

src/tests/testDumpQADB.groovy

@@ -76,6 +76,8 @@ runlistFile.eachLine { runnumStr ->
     // print comment
     println "comment: \"" + qa.getComment() + "\""
 
+    // print helicity sign correction
+    println "helicity sign: ${qa.correctHelicitySign(runnum, evnum)}"
 
     // print overall defect info
     println "- defect"

srcC/include/QADB.h

@@ -13,6 +13,11 @@
 #include <algorithm>
 
 namespace QA {
+
+  int const MISC_BIT       = 5;  // FIXME: should be obtained from `defect_definitions.json`
+  int const BSAWRONG_BIT   = 10;
+  int const BSAUNKNOWN_BIT = 11;
+
   class QADB {
     private:
 
@@ -178,6 +183,7 @@ namespace QA {
         return false;
       }
 
+
       //.................................
       // Faraday Cup charge
       //`````````````````````````````````
@@ -197,6 +203,23 @@ namespace QA {
       inline void ResetAccumulatedCharge() { chargeTotal = 0; };
 
 
+      //.................................
+      // Helicity Sign Correction
+      //`````````````````````````````````
+      // use this method to get the correct helicity sign:
+      // - this method returns -1 if the QA bin has the `BSAWrong` defect,
+      //   which indicates the helicity sign in the data is incorrect
+      // - therefore:
+      //   'true helicity' = 'helicity from data' * CorrectHelicitySign(run_number, event_number)
+      // - zero is returned, if the event is not found in the QADB or if the pion BSA
+      //   sign is not distinguishable from zero
+      // - the return value is constant for a run, but is still assigned per QA bin, for
+      //   full generality
+      // - the return value may NOT be constant for all runs in a data set; for example,
+      //   deviations from the normal value happen when a single run is cooked with the
+      //   wrong HWP position
+      inline int CorrectHelicitySign(int runnum_, int evnum_);
+
 
     private:
 
@@ -487,9 +510,9 @@ namespace QA {
     if(!foundHere)
       return false;
     auto use_mask = mask;
-    if(this->HasDefectBit(5)) {
+    if(this->HasDefectBit(MISC_BIT)) {
       if(allowMiscBitList.find(runnum_) != allowMiscBitList.end())
-        use_mask &= ~(0x1 << 5); // set `use_mask`'s Misc bit to 0
+        use_mask &= ~(0x1 << MISC_BIT); // set `use_mask`'s Misc bit to 0
     }
     return !(defect & use_mask);
   }
@@ -662,6 +685,18 @@ namespace QA {
     };
   };
 
+  //.................................
+  // Helicity Sign Correction
+  //`````````````````````````````````
+  int QADB::CorrectHelicitySign(int runnum_, int evnum_) {
+    bool foundHere = this->Query(runnum_,evnum_);
+    if(!foundHere)
+      return 0;
+    if(this->HasDefectBit(BSAUNKNOWN_BIT))
+      return 0;
+    return this->HasDefectBit(BSAWRONG_BIT) ? -1 : 1;
+  }
+
 };
 
 

srcC/tests/Makefile

@@ -1,4 +1,4 @@
-CXX = g++ -std=c++11
+CXX = g++ -std=c++17
 FLAGS = -g -Wno-deprecated -fPIC -m64 -fno-inline -Wno-write-strings
 
 ifndef QADB

srcC/tests/testCorrectHelicitySign.cpp

@@ -0,0 +1,21 @@
+#include <iostream>
+#include <bitset>
+#include <memory>
+
+#include "QADB.h"
+
+int main(int argc, char ** argv) {
+
+  int runnum;
+  int const EVNUM = 100000; // FIXME: assumption
+  std::string cook;
+  if(argc>2) {
+    cook   = std::string(argv[1]);
+    runnum = std::stoi(argv[2]);
+  }
+  else throw std::runtime_error("arguments must be [cook] [runnum]");
+
+  auto qa = std::make_unique<QA::QADB>(cook);
+  std::cout << qa->CorrectHelicitySign(runnum, EVNUM) << std::endl;
+  return 0;
+}

srcC/tests/testDumpQADB.cpp

@@ -83,6 +83,8 @@ int main(int argc, char ** argv) {
       // print comment
       cout << "comment: \"" << qa->GetComment() << "\"" << endl;
 
+      // print helicity sign correction
+      cout << "helicity sign: " << qa->CorrectHelicitySign(runnum, evnum) << endl;
 
       // print overall defect info
       cout << "- defect" << endl;

util/Makefile

@@ -1,4 +1,4 @@
-CXX = g++ -std=c++11
+CXX = g++ -std=c++17
 FLAGS = -g -Wno-deprecated -fPIC -m64 -fno-inline -Wno-write-strings
 
 # QADB and rapidjson