Intensity Frontier Common Offline Documentation: art Workbook and Users Guide Alpha Release 0.51 December 10, 2013 This version of the documentation is written for version v0 00 15 of the art-workbook code. Scientific Computing Division Future Programs and Experiments Department Scientific Software Infrastructure Group Principal Author: Rob Kutschke Editor: Anne Heavey art Developers: L. Garren, C. Green, J. Kowalkowski, M. Paterno and P. Russo 1 2 Contents Contents 3 art Glossary 13 List of Figures 23 List of Tables 25 Listings 27 I Introduction 3 1 How to Read this Documentation 1 2 Conventions Used in this Documentation 1 3 Introduction to the art Event Processing Framework 1 3.1 What is art and Who Uses it? . 1 3.2 Why art?................................ 2 3.3 C++ and C++11 . 2 3.4 Getting Help . 3 3.5 Overview of the Documentation Suite . 3 3.5.1 The Introduction . 3 3.5.2 The Workbook . 4 3.5.3 Users Guide . 4 3.5.4 Reference Manual . 4 3.5.5 Technical Reference . 5 3.5.6 Glossary . 5 3.6 Some Background Material . 5 3.6.1 Events and Event IDs . 5 3.6.2 art Modules and the Event Loop . 6 3.6.3 Module Types . 9 3.6.4 art Data Products . 10 3.6.5 art Services . 10 3 3.6.6 Shareable Libraries and art .................. 12 3.6.7 Build Systems and art ..................... 12 3.6.8 External Products . 12 3.6.9 The Event-Data Model and Persistency . 14 3.6.10 Event-Data Files . 15 3.6.11 Files on Tape . 15 3.7 The Toy Experiment . 16 3.7.1 Toy Detector Description . 16 3.7.2 Workflow for Running the Toy Experiment Code . 17 3.8 Rules, Best Practices, Conventions and Style . 21 4 Unix Prerequisites 1 4.1 Introduction . 1 4.2 Commands . 1 4.3 Shells . 2 4.4 Scripts: Part 1 . 3 4.5 Unix Environments . 3 4.5.1 Layering Environments . 3 4.5.2 Examining and Using Environment Variables . 4 4.6 Paths and $PATH ........................... 6 4.7 Scripts: Part 2 . 7 4.8 bash Functions and Aliases . 8 4.9 Login Scripts . 8 4.10 Suggested Unix and bash References . 9 5 Site-Specific Setup Procedure 1 6 Get your C++ up to Speed 1 6.1 Introduction . 1 6.2 Establishing the Environment . 2 6.2.1 Initial Setup . 2 6.2.2 Subsequent Logins . 3 6.3 C++ Exercise 1: The Basics . 3 6.3.1 Concepts to Understand . 3 6.3.2 How to Compile, Link and Run . 4 6.3.3 Suggested Homework . 5 6.3.4 Discussion . 5 6.3.5 How was this Exercise Built? . 6 6.4 C++ Exercise 2: About Compiling and Linking . 6 6.4.1 What You Will Learn . 6 6.4.2 The Source Code for this Exercise . 7 6.4.3 Compile, Link and Run the Exercise . 8 6.4.4 Alternate Script build2 ................... 11 6.4.5 Suggested Homework . 12 6.5 C++ Exercise 3: Libraries . 13 6.5.1 What You Will Learn . 14 4 6.5.2 Building and Running the Exercise . 14 6.6 Classes . 17 6.6.1 Introduction . 17 6.6.2 C++ Exercise 4 v1: The Most Basic Version . 18 6.6.3 C++ Exercise 4 v2: The Default Constructor . 22 6.6.4 C++ Exercise 4 v3: Constructors with Arguments . 23 6.6.5 C++ Exercise 4 v4: Colon Initializer Syntax . 25 6.6.6 C++ Exercise 4 v5: Member functions . 27 6.6.7 C++ Exercise 4 v6: Private Data and Accessor Methods . 30 6.6.7.1 Setters and Getters . 30 6.6.7.2 What's the deal with the underscore? . 34 6.6.7.3 An example to motivate private data . 35 6.6.8 C++ Exercise 4 v7: The inline keyword . 35 6.6.9 C++ Exercise 4 v8: Defining Member Functions within the Class Declaration . 37 6.6.10 C++ Exercise 4 v9: The stream insertion operator . 38 6.6.11 Review . 40 6.7 C++ References . 41 7 Using External Products in UPS 1 7.1 The UPS Database List: PRODUCTS . 1 7.2 UPS Handling of Variants of a Product . 3 7.3 The setup Command: Syntax and Function . 3 7.4 Current Versions of Products . 4 7.5 Environment Variables Defined by UPS . 5 7.6 Finding Header Files . 6 7.6.1 Introduction . 6 7.6.2 Finding art Header Files . 6 7.6.3 Finding Headers from Other UPS Products . 8 7.6.4 Exceptions: The Workbook, ROOT and Geant4 . 8 II Workbook 11 8 Preparation for Running the Workbook Exercises 1 8.1 Introduction . 1 8.2 Getting Computer Accounts on Workbook-enabled Machines . 1 8.3 Choosing a Machine and Logging In . 2 8.4 Launching new Windows: Verify X Connectivity . 3 8.5 Choose an Editor . 3 9 Exercise 1: Run Pre-built art Modules 1 9.1 Introduction . 1 9.2 Prerequisites . 1 9.3 What You Will Learn . 1 9.4 Running the Exercise . 2 5 9.4.1 The Pieces . 2 9.4.2 Log In, Set Up and Execute art ................ 2 9.4.2.1 Standard Procedure . 3 9.4.2.2 Procedure allowing Self-managed Working Directory 3 9.5 Logging In Again . 4 9.6 Examine Output . 4 9.7 Understanding the Configuration File hello.fcl ......... 5 9.7.1 Some Bookkeeping Syntax . 5 9.7.2 Some Physics Processing Syntax . 7 9.7.3 Command line Options . 8 9.7.4 Maximum Number of Events to Process . 8 9.7.5 Changing the Input Files . 9 9.7.6 Skipping Events . 11 9.7.7 Identifying the User Code to Execute . 12 9.7.8 Paths . 13 9.7.9 Writing an Output File . 15 9.8 Understanding the Process for Exercise 1 . 16 9.8.1 Follow the Site-Specific Setup Procedure (Details) . 16 9.8.2 Make a Working Directory (Details) . 17 9.8.3 Setup the toyExperiment UPS Product (Details) . 17 9.8.4 Copy Files to your Current Working Directory (Details) . 18 9.8.5 Source makeLinks.sh (Details) . 18 9.8.6 Run art (Details) . 19 9.9 How does art find Modules? . 19 9.10 The art Run-time Environment . 20 9.11 Finding FHiCL files: FHICL FILE PATH . 21 9.11.1 The -c command line argument . 22 9.11.2 #include Files . 22 10 Exercise 2: Build and Run Your First Module 1 10.1 Introduction . 1 10.2 Prerequisites . 2 10.3 What You Will Learn . 3 10.4 Setting up to Run Exercises: Standard Procedure . 3 10.4.1 \Source Window" Setup . 3 10.4.2 Examine Source Window Setup . 4 10.4.2.1 About git and What it Did . 4 10.4.2.2 Contents of the Source Directory . 5 10.4.3 \Build Window" Setup . 5 10.4.4 Examine Build Window Setup . 6 10.5 Setting up to Run Exercises: Self-managed Working Directory . 8 10.6 Logging In Again . 9 10.7 The art Development Environment . 10 10.8 Running the Exercise . 11 10.8.1 Run art on first.fcl ................... 11 10.8.2 The FHiCL File first.fcl ................. 12 6 10.8.3 The Source Code File First module.cc ......... 12 10.8.3.1 The #include Files . 14 10.8.3.2 The Declaration of the Class First ........ 14 10.8.3.3 The Constructor for the Class First ....... 16 10.8.3.4 Aside: Unused Formal Parameters . 17 10.8.3.5 The Member Function analyze and art::Event 18 10.8.3.6 art::EventID .................. 19 10.8.3.7 DEFINE ART MACRO: The Module Maker Macros 21 10.8.3.8 Some Alternate Styles . 22 10.9 What does the Build System Do? . 24 10.9.1 The Basic Operation . ..