Art-Workbook-V0 91
Total Page:16
File Type:pdf, Size:1020Kb
Intensity Frontier Common Offline Documentation: art Workbook and Users Guide Alpha Release 0.91 July 18, 2016 This version of the documentation is written for version v0_00_39 of the art-workbook code. Scientific Computing Division Future Programs and Experiments Department Scientific Software Infrastructure Group Principal Author: Rob Kutschke Other contributors: Marc Paterno, Mike Wang Editor: Anne Heavey art Developers: L. Garren, C. Green, K. Knoepfel, 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 48 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 162 11 General Setup for Login Sessions 219 12 Keeping Up to Date with Workbook Code and Documentation 221 13 Exercise 3: Some other Member Functions of Modules 227 14 Exercise 4: A First Look at Parameter Sets 239 15 Exercise 5: Making Multiple Instances of a Module 264 16 Exercise 6: Accessing Data Products 271 17 Exercise 7: Making a Histogram 291 18 Exercise 8: Looping Over Collections 318 19 3D Event Displays 342 20 Troubleshooting 378 ii III User’s Guide 380 21 git 381 22 art Run-time and Development Environments 390 23 art Framework Parameters 398 24 Job Configuration in art: FHiCL 404 IV Appendices 423 A Obtaining Credentials to Access Fermilab Computing Resources 424 B Installing Locally 426 C art Completion Codes 431 D Viewing and Printing Figure Files 434 E CLHEP 436 F Include Guards 452 V Index 454 Index 455 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 Listing Styles . 5 2.4 Procedures to Follow . 5 2.5 Important Items to Call Out . 6 2.6 Site-specific Information . 6 3 Introduction to the art Event Processing Framework 7 iv 3.1 What is art and Who Uses it? . 7 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 v 4.5.2 Examining and Using Environment Variables . 38 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 48 6.1 Introduction . 48 6.2 File Types Used and Generated in C++ Programming . 49 6.3 Establishing the Environment . 50 6.3.1 Initial Setup . 50 6.3.2 Subsequent Logins . 51 6.4 C++ Exercise 1: Basic C++ Syntax and Building an Executable . 52 6.4.1 Concepts to Understand . 52 6.4.2 How to Compile, Link and Run . 53 6.4.3 Discussion . 55 6.4.3.1 Primitive types, Initialization and Printing Output . 55 6.4.3.2 Arrays . 56 6.4.3.3 Equality testing . 56 6.4.3.4 Conditionals . 57 6.4.3.5 Some C++ Standard Library Types . 57 6.4.3.6 Pointers . 58 6.4.3.7 References . 59 6.4.3.8 Loops . 60 6.5 C++ Exercise 2: About Compiling and Linking . 60 6.5.1 What You Will Learn . 60 6.5.2 The Source Code for this Exercise . 60 6.5.3 Compile, Link and Run the Exercise . 62 6.5.4 Alternate Script build2 ..................... 66 6.5.5 Suggested Homework . 67 6.6 C++ Exercise 3: Libraries . 69 6.6.1 What You Will Learn . 69 vi 6.6.2 Building and Running the Exercise . 69 6.7 Classes . 73 6.7.1 Introduction . 73 6.7.2 C++ Exercise 4 v1: The Most Basic Version . 75 6.7.3 C++ Exercise 4 v2: The Default Constructor . 81 6.7.4 C++ Exercise 4 v3: Constructors with Arguments . 83 6.7.5 C++ Exercise 4 v4: Colon Initializer Syntax . 86 6.7.6 C++ Exercise 4 v5: Member functions . 87 6.7.7 C++ Exercise 4 v6: Private Data and Accessor Methods . 92 6.7.7.1 Setters and Getters . 92 6.7.7.2 What’s the deal with the underscore? . 97 6.7.7.3 An example to motivate private data . 97 6.7.8 C++ Exercise 4 v7: The inline Specifier . 98 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 . 114 7.6.4 Exceptions: The Workbook, ROOT and Geant4 . 115 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 . 123 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 . ..