1. The JANA Calibrations and Conditions Database API March 23, 2009 David Lawrence JLab 3/23/091JANA Calibration API David Lawrence -- JLab

2. The GlueX Experiment 3/23/09JANA Calibration API David Lawrence -- JLab2 real  beam 2 Tesla solenoid magnet 30 cm LH 2 target Forward EM calorimeter and forward TOF wall downstream Cylindrical and planar drift chambers inside magnet Barrel EM calorimeter inside magnet The “continuous wave” 12GeV electron beam at JLab has a beam bunch every 2 ns Conventional meson has quantum numbers determined only by constituent quarks Hybrid meson has some quantum properties due to contributions from the “glue”

3. Data Rates in 12GeV era Front End DAQ Rate Event Size L1 Trigger Rate Bandwidth to mass Storage GlueX3 GB/s15 kB200 kHz300 MB/s CLAS12100 MB/s20 kB10 kHz100 MB/s ALICE500 GB/s2.5 MB200 kHz200 MB/s ATLAS113 GB/s1.5MB75 kHz300 MB/s CMS200 GB/s1 MB100kHz100 MB/s LHCb40 GB/s40 kB1 MHz100 MB/s STAR8 GB/s80 MB100 Hz30 MB/s PHENIX900 MB/s~60 kB~ 15 kHz450 MB/s 3/23/09JANA Calibration API David Lawrence -- JLab3 LHC JLab BNL * CHEP2007 talk Sylvain Chapelin private comm. * NIM A499 Mar. 2003 ppg 762-765 ** CHEP2006 talk MartinL. Purschke **

4. Targeted Customers for JCalibration “B”-coders = reconstruction code authors (“A”-coders = framework authors; “C”-coders = physics analysis) 3/23/09JANA Calibration API David Lawrence -- JLab4 JCalibration URL run_number context (string) … Reconstruction Code namepath (string) STL container ref. Database Reconstruction Program B-codersA-coders The minimal information needed from the reconstruction code is the name of the constants and a container to put them in. (The container implicitly contains a data type.)

5. 5 API For Accessing Constants Constants can be stored in either arrays (1D) or tables (2D) and can be indexed either by name (key-value) or by position. // Get 1-D array of values indexed by name bool Get(string namepath, map &vals) // Get 1-D array of values indexed by row bool Get(string namepath, vector &vals) // Get 2-D table of values indexed by row and name bool Get(string namepath, vector > &vals) // Get 2-D table of values indexed by row and column bool Get(string namepath, vector > &vals) // Get 1-D array of values indexed by name bool Get(string namepath, map &vals) // Get 1-D array of values indexed by row bool Get(string namepath, vector &vals) // Get 2-D table of values indexed by row and name bool Get(string namepath, vector > &vals) // Get 2-D table of values indexed by row and column bool Get(string namepath, vector > &vals) arrays tables 3/23/09JANA Calibration API David Lawrence -- JLab // Get list of available namepaths from backend void GetListOfNamepaths(vector &namepaths) // Get list of available namepaths from backend void GetListOfNamepaths(vector &namepaths) discovery

6. map twpars; loop->Get("FDC/driftvelocity/timewalk_parameters", twpars); slope = twpars["slope"]; offset = twpars["offset"]; exponent = twpars["exponent"]; map twpars; loop->Get("FDC/driftvelocity/timewalk_parameters", twpars); slope = twpars["slope"]; offset = twpars["offset"]; exponent = twpars["exponent"]; 6 Example of Accessing Calibration Constants as key-value pairs... in factory class definition … Template method converts values to doubles using stringstream class For a few parameters like this, it makes sense to copy them into local data members of the factory class 3/23/09JANA Calibration API David Lawrence -- JLab double slope, offset, exponent; double slope, offset, exponent;... in brun() method...

7. Backend Requirements 3/23/09JANA Calibration API David Lawrence -- JLab7 virtual bool GetCalib(string namepath, map &svals) virtual bool GetCalib(string namepath, vector > &svals) virtual void GetListOfNamepaths(vector &namepaths) virtual bool GetCalib(string namepath, map &svals) virtual bool GetCalib(string namepath, vector > &svals) virtual void GetListOfNamepaths(vector &namepaths) To implement a JCalibration interface to a new backend, only 3 virtual methods need to be implemented! OK, actually, it’s closer to 6, but these 3 are for the generator class and are trivial. virtual const char* Description(void) virtual double CheckOpenable(string url, int run, string context) virtual JCalibration* MakeJCalibration(string url, int run, string context) virtual const char* Description(void) virtual double CheckOpenable(string url, int run, string context) virtual JCalibration* MakeJCalibration(string url, int run, string context) The generator mechanism allows access to multiple types of databases in the same executable. Access to a new type can even be brought in through a plugin.

8. Calibration Web Service The JCalibrationWS class provides calibration constants through a web service – Implemented as a plugin so remote access can be added to an existing executable – Allows read-only access to calibration constants from anywhere in the world over HTTP (http://www.jlab.org/Hall-D/cgi-bin/calib) – Uses gSOAP, a C++ SOAP implementation – Currently works like a proxy for JCalibrationFile on server side, but could trivially be made to use another type of backend Calibration constants will need to be accessible from remote computers via the internet Direct access to a database is problematic due to cybersecurity concerns Web services work over HTTP and so are the appropriate mechanism for remote access 3/23/098JANA Calibration API David Lawrence -- JLab

9. Saving a (semi-)complete set of calibration constants to the local disk All JANA programs have the command line option: --dumpcalibrations Records which namepaths are requested during a job and writes the constants into ASCII files compatible with JCalibrationFile Avoids copying and running entire database or even copying a “complete” set of calibration constants (which could include obsolete ones or ones not applicable to the current run/code version) 3/23/099JANA Calibration API David Lawrence -- JLab

10. A simple API for accessing calibration/conditions DB exists in JANA that allows code development prior to developing the actual database – C++ templates + ANSI stringstream allows handling of all data types Web Service is a good option for allowing remote access to constants in a cyber-secure way – SOAP standard (Java, C++, …) JANA has a built-in mechanism for dumping constants to the local disk regardless of the source – Local access is (almost) always faster than network access 3/23/09JANA Calibration API David Lawrence -- JLab10

11. Backup Slides 3/23/09JANA Calibration API David Lawrence -- JLab11

12. Threads in JANA 3/23/09JANA Calibration API David Lawrence -- JLab12 Each thread in JANA is composed of its own event processing loop and a complete set of factories Reconstruction of a given event is done entirely inside of a single thread No mutex locking is required by authors of reconstruction code Threads work asynchronously to maximize rates at the expense of not maintaining the event order on output raw data read in reconstructed values written out (e.g. ROOT tree)

13. 13 Example of Accessing Calibration Constants as an array... in factory class definition... vector tof_tdc_offsets;... in brun() method... loop->GetCalib(”TOF/tdc_offsets", tof_tdc_offsets); if(tof_tdc_offsets.size()!=Ntof) throw JException(“Bad Ntof!”);... in evnt() method... double t = tof->tdc - tof_tdc_offsets[tof->id]; 3/23/09JANA Calibration API David Lawrence -- JLab

14. 14 Backend Database The API defines the routines B-coders will use to obtain calibration constants independent of the details of how the actual database is implemented This does impose some requirements of the database design itself: – Store both 1-D arrays and 2-D tables – Index either by name or position – Uniquely identify constants by Run number Context string (may include timestamp) URL JCalibrationFile implements a trivial calibration backend that maps directly to ASCII files on the local file system – Represents snapshot of constants and so ignores run number and context string – URL points to root directory (e.g. file:///group/halld/calib) – Constants currently kept in svn (https://halldsvn.jlab.org/repos/trunk/calib) 3/23/09JANA Calibration API David Lawrence -- JLab

15. Calibration object generators and namepath Discovery o Generator mechanism for JCalibration JCalibrationGenerator class added Allows multiple types of database backends to be supported in same binary Allows new calibration database backends to be added dynamically to pre-compiled binaries Useful for private development of backend alongside trunk without disturbing standard builds o Discovery mechanism JCalibration now has a new virtual method called GetListOfNamepaths() that can be used to probe a calibration backend for the available constants This is utilized in the jcalibread utility using the “-L” switch 3/23/0915JANA Calibration API David Lawrence -- JLab

16. Recycled Containers... in factory class definition... const double *fcal_gains;... in brun() method... const vector *my_fcal_gains; loop->GetCalib(”FCAL/Energy/gains", my_fcal_gains); fcal_gains = &(my_fcal_gains->front());... in evnt() method... double Ecorr = fcal_hit->E * fcal_gains[fcal_hit->id]; fcal_gains[3] =1.2; // This will generate compile time error! A new templated Get() method has been added to JCalibration that instructs it to keep ownership of the constants and just return a const pointer to the container. Since STL vectors keep internal data sequential in memory, the values can be accessed via a standard array pointer while maintaining const correctness. 3/23/0916JANA Calibration API David Lawrence -- JLab