ComputingTutorials

Introduction

This page is intended for physicists who are just starting to work in the mu2e computing environment. The following is a broad overview of the major components, their terminology, and how you might use them. Following each into paragraph, here are links into more specific tutorials and the rest of the mu2e documentation which is more terse and is intended as a reference once you get through the introductory material.

You probably don't have to work through this entire page and you can stop and any point, please talk to you adviser or mentor to see what's appropriate. The material you are most likely need to use comes first, followed by more in-depth tutorials for people who will be spending years on mu2e and learn to do more complex work.

From time to time we will hold in person tutorials. See In Person Tutorials on the Mu2e internal wiki.

Reporting Errors or Ambiguities

If you find errors or ambiguities in these tutorials, including the accompanying written material, please report them using the issue tracker on the Mu2e/Tutorial GitHub page: https://github.com/Mu2e/Tutorial . The issue button is second from the left on the top of the page. To report an issue you need to join the Mu2e GitHub Organization.

Prerequisites

Have you completed the Mu2e Day 1 CheckList? If not, please do so.

If you have not already done so, please sign up for these slack channels:

tutorial-questions - ask questions about the tutorials here
computing_and_software - the annoucements and general discussion list
is_it_me_or_a_bug - ask questions and about anything except the tutorials.

In this tutorial we will assume you are familiar with the topics below. They are not hard prerequisites. You don't need to master this material before you start but we recommend that you skim it and learn where to look up information when you need it:

The Mu2e detector
- Have a basic idea of the Tracker, Calorimeter and Cosmic Ray Veto System (CRV)
Units and Coordinate Systems Used by Mu2e Offline
Concepts needed to understand Mu2e computing
- Understand, On-spill, off-spill, Event, EventId, Digi, Hit, Track, Cluster, Reconstruction, Simulation
UPS to Spack Transition
bash shell commands
- Beginner Cheat Sheet
- Linux FAQ - includes links to suggested references
The basics of C++. See suggested C++ references.

When you do these exercises you will start on your local computer and log in to one of the Mu2e interactive machines, which are sometimes called the "central machines". The software you will use is on these machines and you will do your work on these machines. You will be working at a terminal window and typing commands at a prompt. The editors available on these machines are: vi, vim, emacs and nedit. If this way is working is not familiar to you, contact a colleague to help get you started.

A Convention You will See

You will sometimes see an instruction that says something like. "To check that this step worked correctly, do"

> echo $PRODUCTS
/cvmfs/fermilab.opensciencegrid.org/products/common/db

The right arrow character represents the shell prompt and you should type everything to the right of that character at the prompt in your working shell. The expected output of that command is known on the following lines. There may be many lines of output. If the output that you see is that same as shown in the example, then everything is working. If the example output contains a version number or a timestamp, it's OK if your output has different values, unless, of course, the example is there explicitly to check the version number.

Interactive logins

Mu2e has 6 machines that you can use for the tutorials: mu2egpvm01 ... mu2egpvm06. For purposes of this tutorial these machines are identical and they all mount the same disks, including your home disk. You can start on one machine and restart on another. Pick one and log in. Last I checked Fermilab security policy broke the automatic load balancer so we need to load balance by hand. If your machine is slow for more than a few minutes, try another.

You login to the mu2e interactive machines using your kerberos principal, "your_username@FNAL.GOV". If you need a refresher on kerberos vs SSO, revisit the Day 1 Checklist.

To login, follow the instructions at: LoginTutorial.
Work through the rest of the page to setup your login scripts, and explore the disks that are available.
If your find ambiguities or errors in the above, let us know on tutorial-questions channel.

Here are some references to know about. You don't need to master them now.

ComputingLogin - lots of hints on resolving issues with logging in.
bash shell -
CodeEnvironment
disks

Ntuple

The data from the detector, and the reconstructed data, is stored in files in art format. Accessing this data generally requires compiling code and learning a special configuration language, so we will save that for a later tutorial. To simplify, and speed up access to the data, we often run a program to copy a small part of the data in the art file into a convenient format call a root ntuple (pronounced "en-tuple"). This format is easy to browser interactively and make histograms. The ntuple file may contain histograms that were already made, or a list of the tracks in each event along with interesting quantities, such as the number of hits on the track or its reconstructed momentum.

Tutorial:

NtupleTutorial is the tutorial for this section and will guide you through making plots with one of the Mu2e-specific ntuples that are available.

Other useful pages:

ROOT is a very useful resource. In particular: getting started and code reference
Overview of existing mu2e ntuples

TrkAnaTutorial

TrkAna is one of the mu2e ntuples.

Tutorial:

The TrkAnaTutorial is hosted on GitHub

Geometry Browser

It is often useful to look at the detector as it is implemented in the simulation either to debug (e.g. double-check the geometry is as you expect) or to get images for presentations.

Tutorial:

Related references:

Code, art and fcl

The main program that is used for simulation, reconstruction and analysis is Mu2e Offline. This is built on top of, art an event processing framework in which the data passes through a series of modules to perform a variety of tasks. Sometimes you will need to build the full Mu2e Offline framework (e.g. if you are a developer) but in other cases you might only need a partial build or use an already existing build.

Tutorial:

The tutorial is now on Mu2e GitHub.
A reminder about the Mu2e CodeEnvironment.

Old material. Obsolete but kept to be scrubbed from good content:

Old CodeArtFclTutorial
ReleaseList gives the list of releases that are available on cvmfs.

Event Display

Not only is it useful to look at the geometry but it is also useful to look at specific events in the simulation to see what is happening.

Tutorial:

The EventDisplayTutorial provides two example tasks to make you familiar with the REve/Mu2e display
- EventDisplays gives an overview of the current ways to display events.

Art Data Products

All objects (e.g. straw hits, calorimeter clusters) are stored in the art event as art data products. These are accessed and created in Offline modules.

Tutorial:

The ArtDataProductTutorial is still to be written but...
- ReadProducts gives information on reading products; and,
- MakeProducts gives information on creating products.

Checkout and build code

If you need to write your own modules or edit code in Offline itself, then you will need your own build of Offline.

Tutorial:

CheckoutAndBuildCodeTutorial is the build system up to spring 2021
MuseBuildCodeTutorial is the build system after spring 2021
- ReleaseList gives the list of releases that are available on cvmfs.

Modules

There are a few different types of art module that you will encounter. "Analyzers" can only analyze data products that are already in the event; "producers" can create new data products; and, "filters" make a decision as to whether an event passes or fails some criteria.

Tutorial:

The ModulesTutorial is still to be written but...
- Modules discusses module names and labels; and
- FilterModules discusses filter modules.

Geometry and Config

For your study, you might need to edit part of the geometry or change the generated particle that is simulated. This is done with config files

Tutorial:

The GeometryAndConfig tutorial is still to be written but...
- SimpleConfig describes the format of these files.

Staging and Mixing Concepts

For the simulation, we don't just run from protons-on-target (POT) all the way through to hits in the tracker and actually run it in stages. This allows us to re-run specific stages to test new geometries without having to run everything again; and it also allows us to generate large samples of specific processes (e.g. particles emitted after a muon is captured by a nucleus) with better efficiency before mixing them all together into a full microbunch event.

Tutorial:

The StagingAndMixingTutorial is still to be written but...
- Staging describes many of the relevant concepts; and,
- Mixing explains background mixing and how to run this type of job.

Datasets and dCache

dCache is the tape system that we use to store our art files.

Tutorial:

The dCacheTutorial is still to be written but...
- Dcache gives a good introduction

Grids

To run large jobs, we use the grid rather than run on a local machine.

Tutorial:

The GridTutorial is still to be written but...
- Grids has a lot of useful information; and,
- Workflows gives a lot of information on how best to organise your work in Mu2e.

Git commits

Git is a version control system that allows us to coordinate many people developing software at the same time. It is widely used in the software development world so you will be able to find a lot of information online.

Tutorial:

The GitTutorial is still to be written but...
- Git has some Mu2e specific information

Code standards

In order to ensure that our code is stable and doing what we expect, there are various tasks where we enforce standard ways of performing them.

Tutorial:

The CodeStandardsTutorial is still to be written but...
- CodingStandards has a nice summary; and,
- RandomNumbers and RandomNumbersBasic describes the way you should generate random numbers in Offline.