Project

General

Profile

About blinding software

Using the Blinding Code

Below are instructions for using the Blinding Code on a g-2 machine with a release of the official framework: this is the SUPPORTED INTERFACE and some instructions to help those who may want to run on their laptop using C++ or python: the latter instructions are likely heavily dependent on your O/S etc and may need to be adapted to your laptop.

Official / Supported Library installation and use

Blinding code (and friends) are installed at the following locations (as of Apr 23, 2018):

  • Blinders: gm2util/blinders/
  • Blinders example code: gm2util/blinders/test/testblinder_module.cc (and notBlinded.fcl)
  • RandomLib: gm2util/blinders/randomlib/ (please refer to http://randomlib.sourceforge.net/html/ for information)

Locations may change as our use of the library evolves.

Blinders Example Code

You can test the code in gm2util/blinders by building gm2util and then running the CMake test facility. First set up the latest Offline release and then execute the following:

mkdir devarea             # setup working area
cd devarea
mrb newDev
. localProducts_*/setup

kinit                     # get gm2util code (develop branch)
mrb gitCheckout gm2util

mrb s                     # setup environment for build
mrb b                     # build
mrb ctest                 # CMake tests

The CMake test of the Blinding code is configured in gm2util/blinders/test/CMakeLists.txt and runs the module testblinder_module.cc through the configuration file notBlinded.fcl. Example usage of the Blinders class in the module's method testblinder::analyze(Event&).

After the CMake test is complete, you should get some output in ${MRB_BUILDDIR}/Testing/Temporary/LastTest.log that looks like this at the top:

----------------------------------------------------------
%MSG-i MF_INIT_OK:  Early 22-Apr-2018 10:17:37 CDT JobSetup
Messagelogger initialization complete.
%MSG
Begin processing the 1st record. run: 1 subRun: 0 event: 1 at 22-Apr-2018 10:17:41 CDT
testblinder::analyze() ...

                     YYYYYYY       YYYYYYY     OOOOOOOOO     UUUUUUUU     UUUUUUUU
                     Y:::::Y       Y:::::Y   OO:::::::::OO   U::::::U     U::::::U
                     Y:::::Y       Y:::::Y OO:::::::::::::OO U::::::U     U::::::U
                     Y::::::Y     Y::::::YO:::::::OOO:::::::OUU:::::U     U:::::UU
                     YYY:::::Y   Y:::::YYYO::::::O   O::::::O U:::::U     U:::::U
                        Y:::::Y Y:::::Y   O:::::O     O:::::O U:::::D     D:::::U
                         Y:::::Y:::::Y    O:::::O     O:::::O U:::::D     D:::::U
                          Y:::::::::Y     O:::::O     O:::::O U:::::D     D:::::U
                           Y:::::::Y      O:::::O     O:::::O U:::::D     D:::::U
                            Y:::::Y       O:::::O     O:::::O U:::::D     D:::::U
                            Y:::::Y       O:::::O     O:::::O U:::::D     D:::::U
                            Y:::::Y       O::::::O   O::::::O U::::::U   U::::::U
                            Y:::::Y       O:::::::OOO:::::::O U:::::::UUU:::::::U
                         YYYY:::::YYYY     OO:::::::::::::OO   UU:::::::::::::UU
                         Y:::::::::::Y       OO:::::::::OO       UU:::::::::UU
                         YYYYYYYYYYYYY         OOOOOOOOO           UUUUUUUUU

                             AAA               RRRRRRRRRRRRRRRRR   EEEEEEEEEEEEEEEEEEEEEE
                            A:::A              R::::::::::::::::R  E::::::::::::::::::::E
                           A:::::A             R::::::RRRRRR:::::R E::::::::::::::::::::E
                          A:::::::A            RR:::::R     R:::::REE::::::EEEEEEEEE::::E
                         A:::::::::A             R::::R     R:::::R  E:::::E       EEEEEE
                        A:::::A:::::A            R::::R     R:::::R  E:::::E
                       A:::::A A:::::A           R::::RRRRRR:::::R   E::::::EEEEEEEEEE
                      A:::::A   A:::::A          R:::::::::::::RR    E:::::::::::::::E
                     A:::::A     A:::::A         R::::RRRRRR:::::R   E:::::::::::::::E
                    A:::::AAAAAAAAA:::::A        R::::R     R:::::R  E::::::EEEEEEEEEE
                   A:::::::::::::::::::::A       R::::R     R:::::R  E:::::E
                  A:::::AAAAAAAAAAAAA:::::A      R::::R     R:::::R  E:::::E       EEEEEE
                 A:::::A             A:::::A   RR:::::R     R:::::REE::::::EEEEEEEE:::::E
                A:::::A               A:::::A  R::::::R     R:::::RE::::::::::::::::::::E
               A:::::A                 A:::::A R::::::R     R:::::RE::::::::::::::::::::E
               AAAAAAA                   AAAAAAARRRRRRRR     RRRRRRREEEEEEEEEEEEEEEEEEEEEE

                    NNNNNNNN        NNNNNNNN     OOOOOOOOO     TTTTTTTTTTTTTTTTTTTTTTT
                    N:::::::N       N::::::N   OO:::::::::OO   T:::::::::::::::::::::T
                    N::::::::N      N::::::N OO:::::::::::::OO T:::::::::::::::::::::T
                    N:::::::::N     N::::::NO:::::::OOO:::::::OT:::::TT:::::::TT:::::T
                    N::::::::::N    N::::::NO::::::O   O::::::OTTTTTT  T:::::T  TTTTTT
                    N:::::::::::N   N::::::NO:::::O     O:::::O        T:::::T
                    N:::::::N::::N  N::::::NO:::::O     O:::::O        T:::::T
                    N::::::N N::::N N::::::NO:::::O     O:::::O        T:::::T
                    N::::::N  N::::N:::::::NO:::::O     O:::::O        T:::::T
                    N::::::N   N:::::::::::NO:::::O     O:::::O        T:::::T
                    N::::::N    N::::::::::NO:::::O     O:::::O        T:::::T
                    N::::::N     N:::::::::NO::::::O   O::::::O        T:::::T
                    N::::::N      N::::::::NO:::::::OOO:::::::O      TT:::::::TT
                    N::::::N       N:::::::N OO:::::::::::::OO       T:::::::::T
                    N::::::N        N::::::N   OO:::::::::OO         T:::::::::T
                    NNNNNNNN         NNNNNNN     OOOOOOOOO           TTTTTTTTTTT

 BBBBBBBBBBBBBBBBB   LLLLLLLLLLL             IIIIIIIIIINNNNNNNN        NNNNNNNNDDDDDDDDDDDDD
 B::::::::::::::::B  L:::::::::L             I::::::::IN:::::::N       N::::::ND::::::::::::DDD
 B::::::BBBBBB:::::B L:::::::::L             I::::::::IN::::::::N      N::::::ND:::::::::::::::DD
 BB:::::B     B:::::BLL:::::::LL             II::::::IIN:::::::::N     N::::::NDDD:::::DDDDD:::::D
   B::::B     B:::::B  L:::::L                 I::::I  N::::::::::N    N::::::N  D:::::D    D:::::D
   B::::B     B:::::B  L:::::L                 I::::I  N:::::::::::N   N::::::N  D:::::D     D:::::D
   B::::BBBBBB:::::B   L:::::L                 I::::I  N:::::::N::::N  N::::::N  D:::::D     D:::::D
   B:::::::::::::BB    L:::::L                 I::::I  N::::::N N::::N N::::::N  D:::::D     D:::::D
   B::::BBBBBB:::::B   L:::::L                 I::::I  N::::::N  N::::N:::::::N  D:::::D     D:::::D
   B::::B     B:::::B  L:::::L                 I::::I  N::::::N   N:::::::::::N  D:::::D     D:::::D
   B::::B     B:::::B  L:::::L                 I::::I  N::::::N    N::::::::::N  D:::::D     D:::::D
   B::::B     B:::::B  L:::::L         LLLLLL  I::::I  N::::::N     N:::::::::N  D:::::D    D:::::D
 BB:::::BBBBBB::::::BLL:::::::LLLLLLLLL:::::LII::::::IIN::::::N      N::::::::NDDD:::::DDDDD:::::D
 B:::::::::::::::::B L::::::::::::::::::::::LI::::::::IN::::::N       N:::::::ND:::::::::::::::DD
 B::::::::::::::::B  L::::::::::::::::::::::LI::::::::IN::::::N        N::::::ND::::::::::::DDD
 BBBBBBBBBBBBBBBBB   LLLLLLLLLLLLLLLLLLLLLLLLIIIIIIIIIINNNNNNNN         NNNNNNNDDDDDDDDDDDDD

 + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +
 +                                                                      +
 +           You have chose to blind your fitting according to          +
 +                omega_ref * (1 + (R +/- deltaR) *10^{-6})             +
 +                                                                      +
 + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +
 + +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +
 +                                                                                       +
 +           You have chose to blind your systematic study fitting according to          +
 +            omega_ref * (1 + (R +/- deltaR)_nominal +/- deltaR_syst) *10^{-6})         +
 +                                                                                       +
 + +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +

 should be unblinded results 
 input R: 0   output: 0
 input R: 1   output: 1e-06
 input R: 2   output: 2e-06
 input R: 3   output: 3e-06
 input R: 4   output: 4e-06
 input R: 5   output: 5e-06
 input R: 6   output: 6e-06
 input R: 7   output: 7e-06
 input R: 8   output: 8e-06
 input R: 9   output: 9e-06

 should be blinded central results 
 input R: 0   output: 4.49788e-06
 input R: 1   output: 5.49788e-06
 input R: 2   output: 6.49788e-06
 input R: 3   output: 7.49788e-06
 input R: 4   output: 8.49788e-06
 input R: 5   output: 9.49788e-06
 input R: 6   output: 1.04979e-05
 input R: 7   output: 1.14979e-05
 input R: 8   output: 1.24979e-05
 input R: 9   output: 1.34979e-05

 should be systematic shift results 
 input R: 0   output: -2.89525e-06
 input R: 1   output: -3.89525e-06
 input R: 2   output: -4.89525e-06
 input R: 3   output: -5.89525e-06
 input R: 4   output: -6.89525e-06
 input R: 5   output: -7.89525e-06
 input R: 6   output: -8.89525e-06
 input R: 7   output: -9.89525e-06
 input R: 8   output: -1.08953e-05
 input R: 9   output: -1.18953e-05
...

Instructions to help getting the code to work on a non g-2 machine using C++ or python.

Note these instructions are not exhaustive and assume that you have some working knowledge of how your laptop is setup !

  • Download getcode.sh and copy this to your favourite GM2 machine. This is currently set to take the Blinding source code from version v8_04_00 but one can simply change the first line "VERSION=vX_YY_ZZ" of this script to whatever version you want. The code shouldn't change so v8_04_00 is fine. Source this script on a g-2 machine:
chmod +x ./getcode.sh
source ./getcode.sh

Having run this script, the two files you need: Blinders.cc and Blinders.hh are in the directory: srcs/gm2util/blinders
Copy these two files to your laptop.

  • Go to your laptop and create a "blinding" subdirectory. In what follows we will assume XX is the parent directory of blinding e.g.
    cd /Users/markl/g-2/test  #  XX is /Users/markl/g-2/test
    mkdir blinding
    cd blinding
    

In this directory (XX/blinding) put Blinders.cc and Blinders.hh that you have copied from the GM2 machine.
Download: RandomLib-1.10.tar.gz

Unpack and compile Random.cpp

tar -xzf RandomLib-1.10.tar.gz
ln -sf RandomLib-1.10 rlib
cd rlib/src
g++ -g -Wall -Wextra -O3 -funroll-loops -finline-functions -fomit-frame-pointer -fpic -I../include -c -o Random.o Random.cpp

Note Blinders.cc needs to have a modern g++ version since it implements features supported by c++11 -- i.e. you need a g++ version beyond
4.8.0 e.g. the default version on the g-2 virtual machines (ie the one not setup by the offline environment) is not c++11 compliant and will not work.

Next you need to modify Blinders.cc and Blinders.hh

 cd XX/blinding 

Change:

#include "gm2util/blinders/Blinders.hh" 
#include "gm2util/blinders/randomlib/NormalDistribution.hh" 

in Blinders.cc to be

#include "Blinders.hh" 
#include "RandomLib/NormalDistribution.hpp" 

and also immediately after the line:

using namespace blinding;

add this:

// Code in extern to enable python access
#ifdef __cplusplus
extern "C" {
#include "python_header.h" 
  }
#endif

and in Blinders.hh replace:

#include "gm2util/blinders/randomlib/Random.hh" 

with

#include "RandomLib/Random.hpp" 

Then download python_header.h and put this in XX/blinding

Now compile Blinders.cc :

cd XX/blinding
g++ -I rlib/include -I INCLUDEPATH Blinders.cc -std=c++11 -Wall -Wextra -Werror -pedantic-errors -fpic -c

Here you may have trouble with #include <openssl/md5.h> in Blinders.cc and hence need to have INCLUDEPATH set to a path where you have openssl/md5.h. On a MAC if you have installed openssl via homebrew then INCLUDEPATH being /usr/local/opt/openssl/include works OK. md5.h is installed with some (older) versions of the XCode Developer tools but not the latest version i.e. this will work:

g++ -I rlib/include -I /usr/local/opt/openssl/include Blinders.cc -std=c++11 -Wall -Wextra -Werror -pedantic-errors -fpic -c

On Linux you should be OK without having to set INCLUDEPATH to anything since md5.h is in /usr/include/openssl and /usr/include is already a default -I path.

Now create a shared object library that can be used with both ROOT and standalone

cd XX/blinding
g++ -shared -o libBlinders.so Blinders.o rlib/src/Random.o -lssl -lcrypto

Here again you may run into issues if you do not have openssl installed since you need the "-lssl -lcrypto" for the link to work.
If you see this error:

ld: library not found for -lssl

run this:

g++ -shared -o libBlinders.so Blinders.o rlib/src/Random.o -L/usr/local/opt/openssl/lib -lssl -lcrypto 

You are now ready to run some test-code: download the standalone C++ testBlinding.cc and the ROOT macro testBlinding.C and put it in XX/blinding.

You now need to set a sensible LD_LIBRARY_PATH that includes the path to libBlinders.so (which is XX/blinding) and also the ROOT shared object libraries e.g. for homebrew ROOT: /usr/local/Cellar/root/6.12.06/lib/root or $ROOTSYS/lib on Linux etc. See for example:

export LD_LIBRARY_PATH=/Users/markl/g-2/test/blinding:/usr/local/Cellar/root/6.12.06/lib/root:/lib

Then you can compile and link the standalone C++:

cd XX/blinding
g++ -I rlib/include testBlinding.cc -L./ -lBlinders -o testBlinding.exe
./testBlinding.exe

You should then see the same output as above for the supported, official release.

Or you can run the ROOT macro (testBlinding.C) as follows:

root -l
root [0] gSystem->Load("./libBlinders.so");
root [1] gROOT->ProcessLine(".include ./rlib/include/");
root [1] .x testBlinding.C
root [2] .q

and again you should see the same output.

Example blinded fit using ROOT macro

An example for wiggle plot fitting is given in fitWithBlinders.C. Please download the file gm2offline_example.root into the same folder where you want to run the macro.

root -l
root [0] gSystem->Load("./libBlinders.so");
root [1] gROOT->ProcessLine(".include ./rlib/include/");
root [1] .x fitWithBlinders.C
root [2] .q

Example blinded fit using ROOT macro with access to blinders shared object library (ROOT version 6.04 or later)

If you have access to the blinders shared object library, for instance if you've built the gm2util package but are running your analysis code within root macros in a gm2analyses branch, then there is an easy way to link the blinding code. At the beginning of your root macro add

R__LOAD_LIBRARY(/gm2/app/users/nkinnaird/RatioAnalysis/gm2Dev_v8_04_00/build_slf6.x86_64/gm2util/lib/libgm2util_blinders.so)

where within the parentheses is the path to your shared object library. (Note the lack of quotes, and the double underscore at R__LOAD.) Then include

#include "gm2util/blinders/Blinders.hh" 
using namespace blinding;

or whatever the include path is to the Blinders.hh file, and you're away. As an added benefit this nicely allows you to run your root macro without having to load anything from the root command line first. This probably also applies to the libBlinders.so library mentioned in the above section, but it hasn't been tested.

Alternatively, one can add the following, for example to the gm2 setup.sh script:

echo "R__LOAD_LIBRARY("${MRB_BUILDDIR}"/gm2util/lib/libgm2util_blinders.so)" > $OFFLINE/$WORKSPACE/srcs/gm2analyses/"incRLoad.hh" 

This will print the "R__LOAD_LIBRARY" path with the current gm2 software version into the file called "incRLoad.hh".
The include to all the ROOT macros now becomes
//path to the master R__LOAD_LIBRARY file 
#include "gm2analyses/incRLoad.hh" 
#include "gm2util/blinders/Blinders.hh" 
using namespace blinding;

The advantage of this method, is the automated way the incRLoad.hh is generated, based on your current gm2 release. So, there is no need to ever update the "R__LOAD_LIBRARY" path in multiple macros.
P.S. "symbol lookup error: libgm2util_blinders.so: undefined symbol: MD5" is resolved by adding this line to your ROOT macro
#include "TTree.h" 

Using the code in Python

Python 2

To use the python interface you should have already created libBlinders.so (having included "python_header.h" in Blinders.cc as detailed above).
This has been tested using python 2.7 on a Mac & Linux. You need to download testBlinding.py and Blinders.py to your XX/blinding directory i.e. the location of libBlinders.so

python testBlinding.py # assuming python points to python v2.7+ not 3.x

Python 3

This has been tested using python 3.6 on a Mac. You need to download testBlindingPy3.py and BlindersPy3.py to your XX/blinding directory i.e. the location of libBlinders.so

python3 testBlindingPy3.py 

Both Python2 and Python3 versions run the same code as testBlinding.cc and calls the C++ code via a ctypes wrapper. It should produce the same output as testBlinding.cc and testBlinding.C

Python Jupyter Notebook + ROOT

An example of blinded fit using jupyter notebook and ROOT is shown here, ipynb and here, pdf. Please download the file gm2offline_example.root into the same folder where you want to run the notebook.

Blinded fit without using official libraries (use at your own risk!)

An example of blinded fit using ROOT functions (Hash and TRandom3) is also provided here: simpleBlinders.C. You are encouraged to using the official library unless your operating system is not compatible with it. Please download the file gm2offline_example.root into the same folder where you want to run the macro.

root -l simpleBlinders.C