ComputingTutorials: Difference between revisions
(55 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
==Introduction== | ==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. | 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. | 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 | |||
[https://mu2einternalwiki.fnal.gov/wiki/In_Person_Tutorials 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 [[GitHubWorkflow#Make_your_Own_GitHub_Account_and_Join_the_Mu2e_GitHub_Organization | join the Mu2e GitHub Organization]]. | |||
==Prerequisites== | ==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 [[LearnAboutMu2e|Mu2e detector]] | |||
** Have a basic idea of the Tracker, Calorimeter and Cosmic Ray Veto System (CRV) | |||
* [https://mu2e-docdb.fnal.gov/cgi-bin/sso/ShowDocument?docid=1120 Units and Coordinate Systems Used by Mu2e Offline] | |||
* [[Computing Concepts|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 | |||
** [[Shells#Beginner_Cheat_Sheet | Beginner Cheat Sheet]] | |||
** [[LinuxFAQ|Linux FAQ]] - includes links to suggested references | |||
* The basics of C++. See [[CppFAQ#What_C.2B.2B_References_are_Recommended.3F | 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 [[Day_1_CheckList#Computer_Accounts | 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. | |||
* [[ | * [[Shells|bash shell]] - | ||
* [[CodeEnvironment]] | |||
* [[ | |||
* [[Disks|disks]] | * [[Disks|disks]] | ||
==[[NtupleTutorial|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: | |||
* [https://root.cern.ch/ ROOT] is a very useful resource. In particular: [https://root.cern.ch/getting-started getting started] and [https://root.cern.ch/guides/reference-guide code reference] | |||
* Overview of existing [[Ntuples|mu2e ntuples]] | |||
==TrkAnaTutorial== | |||
[[TrkAna]] is one of the mu2e ntuples. | |||
Tutorial: | |||
* The [https://github.com/Mu2e/TrkAna/blob/main/tutorial/README.md TrkAnaTutorial] is hosted on GitHub | |||
==Geometry Browser== | ==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: | |||
* [[GeometryBrowserTutorial2019 | Geometry browser tutorial, revised for June 2019]] | |||
* [[GeometryBrowserTutorial| Geometry browser tutorial from summer 2016]] | |||
Related references: | |||
* [[Geometry]] | |||
* [[EventDisplays]] | |||
==Code, art and fcl== | ==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 [https://github.com/Mu2e/Tutorial/blob/main/AllInOne/doc/AllInOne.md 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. | |||
<!-- | |||
where is the code (do not run git yet tho), intro to releases, cvmfs, run genReco, set output file names and Nevents | where is the code (do not run git yet tho), intro to releases, cvmfs, run genReco, set output file names and Nevents | ||
intro to fcl, paths and filters. maybe a couple of tutorials? | intro to fcl, paths and filters. maybe a couple of tutorials? | ||
--> | |||
==Event Display== | ==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 Mu2eEventDisplay 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. | |||
<!--- | |||
print and dump files, list products, write input tags. Maybe look at RecoDataProducts | print and dump files, list products, write input tags. Maybe look at RecoDataProducts | ||
---> | |||
==Checkout and build code== | ==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. | |||
<!--- | |||
scons, satellite releases, warning about changing include files | scons, satellite releases, warning about changing include files | ||
---> | |||
==Modules== | ==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. | |||
<!--- | |||
example module code. access a product, make histograms, | example module code. access a product, make histograms, | ||
write a product(?) | write a product(?) | ||
access geometry and config | access geometry and config | ||
---> | |||
==Geometry and Config== | ==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. | |||
<!--- | |||
alter a geometry file, examine a generator config file | alter a geometry file, examine a generator config file | ||
---> | |||
==Staging and Mixing Concepts== | ==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. | |||
<!--- | |||
run multi-stage, run mixing, make fcl changes and re-run | run multi-stage, run mixing, make fcl changes and re-run | ||
---> | |||
==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 | |||
<!--- | |||
explain dCache, write to scratch dcache, use ifdh, intro to upload? | explain dCache, write to scratch dcache, use ifdh, intro to upload? | ||
---> | |||
==Grids== | ==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. | |||
<!--- | |||
build and submit a mu2eprodsys job, second tutorial to monitor the job | build and submit a mu2eprodsys job, second tutorial to monitor the job | ||
---> | |||
==Git commits== | ==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 | |||
<!--- | |||
provide a scratch repo that they can checkout and commit to randomly. Walk through both commit patterns | provide a scratch repo that they can checkout and commit to randomly. Walk through both commit patterns | ||
---> | |||
==Code standards== | ==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. | |||
<!--- | |||
code style, art standards, random numbers, CLHEP, boost, magic numbers | code style, art standards, random numbers, CLHEP, boost, magic numbers | ||
---> | |||
==References and resources== | ==References and resources== | ||
The best ways to get help can be found on the [[ComputingHelp]] page. | |||
<!--- | |||
discuss when and how to get help, maybe tour the wiki? | discuss when and how to get help, maybe tour the wiki? | ||
---> | |||
==Random Links (scratch)== | ==Random Links (scratch)== | ||
[https://mu2e-docdb.fnal.gov | [https://mu2e-docdb.fnal.gov/cgi-bin/sso/DisplayMeeting?sessionid=3729 latest meeting] | ||
Sarah's [https://docs.google.com/document/d/1YuwYfarDO7d2ficXsjpMr-yYfFo4l72FNPEZT4rfkjQ/edit google doc] on clickable status and intro paragraphs | Sarah's [https://docs.google.com/document/d/1YuwYfarDO7d2ficXsjpMr-yYfFo4l72FNPEZT4rfkjQ/edit google doc] on clickable status and intro paragraphs | ||
Rob's 10/26/17 [https://mu2e-docdb.fnal.gov | Rob's 10/26/17 [https://mu2e-docdb.fnal.gov/cgi-bin/sso/ShowDocument?docid=14074 talk] on intro to computing plan | ||
[http://mu2e.fnal.gov/atwork/tmp/ clickable detector] | [http://mu2e.fnal.gov/atwork/tmp/ clickable detector] | ||
[[CodeRecipe|Build recipe]] | [[CodeRecipe|Build recipe]] | ||
Line 137: | Line 259: | ||
July 2016 intro talks | July 2016 intro talks | ||
[https://mu2e-docdb.fnal.gov | [https://mu2e-docdb.fnal.gov/cgi-bin/sso/ShowDocument?docid=7746 Software tutorial] | ||
[https://mu2e-docdb.fnal.gov | [https://mu2e-docdb.fnal.gov/cgi-bin/sso/ShowDocument?docid=7859 Practicalities of MC] | ||
[https://mu2e-docdb.fnal.gov | [https://mu2e-docdb.fnal.gov/cgi-bin/sso/ShowDocument?docid=7861 Hits and Mixing] | ||
[[Category:Computing]] | [[Category:Computing]] |
Latest revision as of 15:06, 14 October 2024
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 Mu2eEventDisplay 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...
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...
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.
References and resources
The best ways to get help can be found on the ComputingHelp page.
Random Links (scratch)
Sarah's google doc on clickable status and intro paragraphs
Rob's 10/26/17 talk on intro to computing plan
Rob's first geant run for new users
Summer 2016 SCD workshops (includes geometry tutorial)
July 2016 intro talks
Tutorials (scratch)
- Testing the ROOT display
- Testing the Geant4 based event display
- Notes on dynamic libraries
- The First Step: the art workbook
- Running G4 within art: The first examples.
- Mu2e maintained FAQs: C++ FAQ, Unix/Linux FAQ, ROOT FAQ, Geant4 Notes