Intensity Frontier Common Offline Documentation: art Workbook and Users Guide Alpha Release 0.84 August 18, 2014 This version of the documentation is written for version v0_00_27 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 List of Chapters Detailed Table of Contents iv List of Figures xx List of Tables xxii List of Code and Output Listings xxii art Glossary xxvii I Introduction 1 1 How to Read this Documentation 2 2 Conventions Used in this Documentation 4 3 Introduction to the art Event Processing Framework 7 4 Unix Prerequisites 34 5 Site-Specific Setup Procedure 45 i 6 Get your C++ up to Speed 47 7 Using External Products in UPS 107 II Workbook 119 8 Preparation for Running the Workbook Exercises 120 9 Exercise 1: Running Pre-built art Modules 124 10 Exercise 2: Building and Running Your First Module 163 11 General Setup for Login Sessions 220 12 Keeping Up to Date with Workbook Code and Documentation 222 13 Exercise 3: Some other Member Functions of Modules 228 14 Exercise 4: A First Look at Parameter Sets 240 15 Exercise 5: Making Multiple Instances of a Module 265 16 Exercise 6: Accessing Data Products 272 17 Exercise 7: Making a Histogram 291 18 Exercise 8: Looping Over Collections 317 19 3D Event Displays 341 20 Troubleshooting 377 ii III User’s Guide 379 21 Obtaining Credentials to Access Fermilab Computing Resources 380 22 git 382 23 art Run-time and Development Environments 391 24 art Framework Parameters 399 25 Job Configuration in art: FHiCL 405 IV Appendices 424 A art Completion Codes 425 B Viewing and Printing Figure Files 428 C CLHEP 430 D Include Guards 446 V Index 448 Index 449 iii Detailed Table of Contents Detailed Table of Contents iv List of Figures xx List of Tables xxii List of Code and Output Listings xxii art Glossary xxvii I Introduction 1 1 How to Read this Documentation 2 1.1 If you are new to HEP Software... 2 1.2 If you are an HEP Software expert... 2 1.3 If you are somewhere in between... 3 2 Conventions Used in this Documentation 4 2.1 Terms in Glossary . 4 2.2 Typing Commands . 4 2.3 Procedures to Follow . 5 2.4 Important Items to Call Out . 5 2.5 Site-specific Information . 6 3 Introduction to the art Event Processing Framework 7 3.1 What is art and Who Uses it? . 7 iv 3.2 Why art?.................................. 8 3.3 C++ and C++11 . 9 3.4 Getting Help . 9 3.5 Overview of the Documentation Suite . 9 3.5.1 The Introduction . 11 3.5.2 The Workbook . 11 3.5.3 Users Guide . 12 3.5.4 Reference Manual . 12 3.5.5 Technical Reference . 12 3.5.6 Glossary . 12 3.6 Some Background Material . 12 3.6.1 Events and Event IDs . 13 3.6.2 art Modules and the Event Loop . 14 3.6.3 Module Types . 18 3.6.4 art Data Products . 19 3.6.5 art Services . 20 3.6.6 Dynamic Libraries and art ..................... 21 3.6.7 Build Systems and art ....................... 22 3.6.8 External Products . 23 3.6.9 The Event-Data Model and Persistency . 24 3.6.10 Event-Data Files . 25 3.6.11 Files on Tape . 26 3.7 The Toy Experiment . 26 3.7.1 Toy Detector Description . 27 3.7.2 Workflow for Running the Toy Experiment Code . 29 3.8 Rules, Best Practices, Conventions and Style . 33 4 Unix Prerequisites 34 4.1 Introduction . 34 4.2 Commands . 34 4.3 Shells . 36 4.4 Scripts: Part 1 . 36 4.5 Unix Environments . 37 4.5.1 Building up the Environment . 37 4.5.2 Examining and Using Environment Variables . 38 v 4.6 Paths and $PATH . 39 4.7 Scripts: Part 2 . 41 4.8 bash Functions and Aliases . 42 4.9 Login Scripts . 43 4.10 Suggested Unix and bash References . 43 5 Site-Specific Setup Procedure 45 6 Get your C++ up to Speed 47 6.1 Introduction . 47 6.2 File Types Used and Generated in C++ Programming . 48 6.3 Establishing the Environment . 49 6.3.1 Initial Setup . 49 6.3.2 Subsequent Logins . 50 6.4 C++ Exercise 1: Basic C++ Syntax and Building an Executable . 51 6.4.1 Concepts to Understand . 51 6.4.2 How to Compile, Link and Run . 52 6.4.3 Discussion . 54 6.4.3.1 Primitive types, Initialization and Printing Output . 54 6.4.3.2 Arrays . 55 6.4.3.3 Equality testing . 55 6.4.3.4 Conditionals . 56 6.4.3.5 Some C++ Standard Library Types . 56 6.4.3.6 Pointers . 57 6.4.3.7 References . 58 6.4.3.8 Loops . 59 6.5 C++ Exercise 2: About Compiling and Linking . 59 6.5.1 What You Will Learn . 59 6.5.2 The Source Code for this Exercise . 59 6.5.3 Compile, Link and Run the Exercise . 61 6.5.4 Alternate Script build2 ..................... 65 6.5.5 Suggested Homework . 66 6.6 C++ Exercise 3: Libraries . 68 6.6.1 What You Will Learn . 68 6.6.2 Building and Running the Exercise . 68 vi 6.7 Classes . 72 6.7.1 Introduction . 72 6.7.2 C++ Exercise 4 v1: The Most Basic Version . 74 6.7.3 C++ Exercise 4 v2: The Default Constructor . 80 6.7.4 C++ Exercise 4 v3: Constructors with Arguments . 82 6.7.5 C++ Exercise 4 v4: Colon Initializer Syntax . 85 6.7.6 C++ Exercise 4 v5: Member functions . 86 6.7.7 C++ Exercise 4 v6: Private Data and Accessor Methods . 91 6.7.7.1 Setters and Getters . 91 6.7.7.2 What’s the deal with the underscore? . 96 6.7.7.3 An example to motivate private data . 96 6.7.8 C++ Exercise 4 v7: The inline Specifier . 97 6.7.9 C++ Exercise 4 v8: Defining Member Functions within the Class Declaration . 100 6.7.10 C++ Exercise 4 v9: The Stream Insertion Operator and Free Func- tions . 101 6.7.11 Review . 105 6.8 Overloading functions . 105 6.9 C++ References . 105 7 Using External Products in UPS 107 7.1 The UPS Database List: PRODUCTS . 107 7.2 UPS Handling of Variants of a Product . 109 7.3 The setup Command: Syntax and Function . 109 7.4 Current Versions of Products . 111 7.5 Environment Variables Defined by UPS . 111 7.6 Finding Header Files . 112 7.6.1 Introduction . 112 7.6.2 Finding art Header Files . 113 7.6.3 Finding Headers from Other UPS Products . 115 7.6.4 Exceptions: The Workbook, ROOT and Geant4 . 116 vii II Workbook 119 8 Preparation for Running the Workbook Exercises 120 8.1 Introduction . 120 8.2 Getting Computer Accounts on Workbook-enabled Machines . 120 8.3 Choosing a Machine and Logging In . 121 8.4 Launching new Windows: Verify X Connectivity . 122 8.5 Choose an Editor . 122 9 Exercise 1: Running Pre-built art Modules 124 9.1 Introduction . 124 9.2 Prerequisites . 124 9.3 What You Will Learn . 124 9.4 The art Run-time Environment . 125 9.5 The Input and Configuration Files for the Workbook Exercises . 126 9.6 Setting up to Run Exercise 1 . 127 9.6.1 Log In and Set Up . 127 9.6.1.1 Initial Setup Procedure using Standard Directory . 127 9.6.1.2 Initial Setup Procedure allowing Self-managed Working Directory . 129 9.6.1.3 Setup for Subsequent Exercise 1 Login Sessions . 130 9.7 Execute art and Examine Output . 130 9.8 Understanding the Configuration . 132 9.8.1 Some Bookkeeping Syntax . ..