Intensity Frontier Common Offline Documentation: art Workbook and Users Guide Alpha Release 0.82 August 7, 2014 This version of the documentation is written for version v0_00_26 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 xxv 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 105 II Workbook 117 8 Preparation for Running the Workbook Exercises 118 9 Exercise 1: Running Pre-built art Modules 122 10 Exercise 2: Building and Running Your First Module 161 11 General Setup for Login Sessions 218 12 Keeping Up to Date with Workbook Code and Documentation 220 13 Exercise 3: Some other Member Functions of Modules 226 14 Exercise 4: A First Look at Parameter Sets 238 15 Exercise 5: Making Multiple Instances of a Module 263 16 Exercise 6: Accessing Data Products 270 17 Exercise 7: Making a Histogram 289 18 Exercise 8: Looping Over Collections 314 19 Troubleshooting 338 ii III User’s Guide 340 20 Obtaining Credentials to Access Fermilab Computing Resources 341 21 git 343 22 art Run-time and Development Environments 352 23 art Framework Parameters 360 24 Job Configuration in art: FHiCL 366 IV Appendices 385 A art Completion Codes 386 B Viewing and Printing Figure Files 389 C CLHEP 391 V Index 407 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 xxv 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 . 47 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 . 53 6.4.3.1 Primitive types . 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 . 56 6.4.3.7 References . 58 6.4.3.8 Loops . 58 6.5 C++ Exercise 2: About Compiling and Linking . 58 6.5.1 What You Will Learn . 58 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 ..................... 64 6.5.5 Suggested Homework . 66 6.6 C++ Exercise 3: Libraries . 67 6.6.1 What You Will Learn . 67 6.6.2 Building and Running the Exercise . 67 vi 6.7 Classes . 72 6.7.1 Introduction . 72 6.7.2 C++ Exercise 4 v1: The Most Basic Version . 73 6.7.3 C++ Exercise 4 v2: The Default Constructor . 78 6.7.4 C++ Exercise 4 v3: Constructors with Arguments . 81 6.7.5 C++ Exercise 4 v4: Colon Initializer Syntax . 84 6.7.6 C++ Exercise 4 v5: Member functions . 86 6.7.7 C++ Exercise 4 v6: Private Data and Accessor Methods . 90 6.7.7.1 Setters and Getters . 90 6.7.7.2 What’s the deal with the underscore? . 95 6.7.7.3 An example to motivate private data . 96 6.7.8 C++ Exercise 4 v7: The inline Specifier . 96 6.7.9 C++ Exercise 4 v8: Defining Member Functions within the Class Declaration . 98 6.7.10 C++ Exercise 4 v9: The stream insertion operator . 99 6.7.11 Review . 102 6.8 Overloading functions . 103 6.9 C++ References . 103 7 Using External Products in UPS 105 7.1 The UPS Database List: PRODUCTS . 105 7.2 UPS Handling of Variants of a Product . 107 7.3 The setup Command: Syntax and Function . 107 7.4 Current Versions of Products . 109 7.5 Environment Variables Defined by UPS . 109 7.6 Finding Header Files . 110 7.6.1 Introduction . 110 7.6.2 Finding art Header Files . 111 7.6.3 Finding Headers from Other UPS Products . 113 7.6.4 Exceptions: The Workbook, ROOT and Geant4 . 114 II Workbook 117 8 Preparation for Running the Workbook Exercises 118 vii 8.1 Introduction . 118 8.2 Getting Computer Accounts on Workbook-enabled Machines . 118 8.3 Choosing a Machine and Logging In . 119 8.4 Launching new Windows: Verify X Connectivity . 120 8.5 Choose an Editor . 120 9 Exercise 1: Running Pre-built art Modules 122 9.1 Introduction . 122 9.2 Prerequisites . 122 9.3 What You Will Learn . 122 9.4 The art Run-time Environment . 123 9.5 The Input and Configuration Files for the Workbook Exercises . 124 9.6 Setting up to Run Exercise 1 . 125 9.6.1 Log In and Set Up . 125 9.6.1.1 Initial Setup Procedure using Standard Directory . 125 9.6.1.2 Initial Setup Procedure allowing Self-managed Working Directory . 127 9.6.1.3 Setup for Subsequent Exercise 1 Login Sessions . 128 9.7 Execute art and Examine Output . 128 9.8 Understanding the Configuration . 130 9.8.1 Some Bookkeeping Syntax . 130 9.8.2 Some Physics Processing Syntax . ..