Installing the Mu2e Tool Chain

This page explains how to install prebuilt binary versions of the software tool chain needed to build and run Mu2e Offline at a remote site; here a "remote site" means any computer that does not mount one of:

1. the bluearc disk /grid/fermiapp/product/mu2e
2. the Mu2e CVMFS partition: /cvmfs/mu2e.opensciencegrid.org

Should you need/wish to build the tool chain from source, you can follow the instructions for building the tool chain from source.

Table of Contents

• Introduction
• Supported Operating Systems
• Collecting Information
• Temporary Instructions for art v1_15_00
• Cheat Sheet: art v1_12_04 and later
• Cheat Sheet: art v1_12_02 only

The difference between the last two options is where you put the version number of the requested version of art. In the script for v1_12_02 and earlier a new download script is created for each new release and the version number is embedded into the screipt name. In the script for v1_12_04 and script does not change from version to version and the version number is supplied as an argument to the script.

Version v1_12_03 was an integration release will not be distributed.

Introduction

The tool chain needed to run Mu2e Offline at a remote site includes the following parts:

1. A UPS repository containing art, the UPS packages on which it depends, geant4, scons and a few other packages. You may also wish to read the Mu2e documentation on UPS.
2. The site specific setup script; you need to copy this file from Fermilab and make a few edits to describe your local environment. At Fermilab, this is the script that is invoked when you type the command "setup mu2e".
3. The magnetic field map files.
4. The example stopped muon input file; this is needed to run the introductory examples but may not been needed for other purposes.

The above files may be owned by any user, provided they are readable, and, if appropriate, executable, by Mu2e users at your site. However we do suggest that you create a separate account for installing these files; this way you cannot accidentally delete them when logged in to your own account; if you decide to use a separate account, there are no restrictions on the name of the account but it should be in the same group as regular Mu2e users and the files should be group readable and, if appropriate, group executable. In summary, using a separate account to own the tool chain is not necessary but it is a recommended saftey practice.

Supported Operating Systems

The table below lists the operating systems for which the art team provides binary distributions. The binary distributions are built for 64 bit hardware but not for 32 bit hardware.

For the MAC OSX versions, the letter "d" in the mnemonic names "d12" and "d13" refers to "Darwin", which is Apple's name for OSX. The d12 version is known to work when run on a few specific earlier releases of Mac OS, specifically, Snow Leopard (OSX 10.8) and Lion (OSX 11).

Officially the art team does not support Scientific Linux CERN (SLC) or plain Scientific Linux (SL) but several users have reported that installing the SLF binaries on SLC or SL machines "just works". This is not surprising since the differences among these OS versions involve only authentication.

If you wish to use the Mu2e Offline on a platform not discussed above, you will need to build the tool chain from source.

If you have a large computing resource that runs an OS not listed above, you can ask the art team to provide a binary distribution for that platform. For this to happen you will need to give them access to an appropriate machine on which they can build the software. The art team is only likely to agree to this if you are bringing a signficant computing resource to the table.

Collecting Information

Before you run the installation tools you need to decide where to install the software and you need to learn some information about the platform on which you are doing the installation.

1. Decide where to install the tool chain. In the following we will presume that you have described this choice by defining the environment variable MU2E_TOP:

   export MU2E_TOP=/absolute/path/to/your/local/mu2e/top_level/directory
   

2. Decide the memonic name of the platform that you wish to install: one of slf5, slf6, d12 or d13.
3. Decide on which art version you wish to install, for example

   export ART_VERSION=v1_15_00
   

   Consult Offline/setup.sh to learn which version of art you need to download; you can also consult the Mu2e software team.
4. Decide on the UPS options for the packages in the tool chain, for example:

   export ART_OPTIONS=s13-e7
   

   See the table below to learn which ART_OPTIONS are required/allowed for which ART_VERSION.

The art team maintains a page that describes the art options. The two options shown in the above example are e7 and s12; each of the numbered e options chooses a compiler version plus compiler flags. The numbered s options are used by products that depend on an art version (for example ifdh_art), not by art itself; the s option is a mnemonic for which vesion of art it depends on.

The table below gives the correct values of ART_VERSION and ART_OPTIONS for all versions of art that have been used by Mu2e, starting from art v1_12_04.

Temporary Instructions for art v1_15_00

Mu2e is currently in a transition. Starting on July 6, 2015, the BaBar code will be distributed as a ups product, named BTrk. Later in the summer Mu2e Offline will be broken into several pieces, each of which is distributed as a ups product. The ups product distribution system needs to be upgraded to deal with this. While this upgrade is in progress, please follow the temporary instructions below.

1. With exceptions described below, follow the cheat sheet for art v1_12_04 and later.
2. In steps 5 and 6 of the v1_12_04 instructions, the third argument to pullProducts should be mu-${ART_VERSION}, not mu2e-${ART_VERSION}.

   Note the change in the prefix from mu2e to mu.
   

3. After step 6 and before step 7 of the v1_12_04 instructions,

        cd ../tmp
        scp your_kerberos_principle@mu2egpvm01.fnal.gov:/grid/fermiapp/products/mu2e/Downloads/BTrk_v1_00_08.tar.gz .
        cd ../artexternals
        tar xzf ../tmp/BTrk_v1_00_08.tar.gz     

   This copies a gzipped tar file that contains the required version of the BTrk ups product. It then installs it at the right spot in the artexternals directory.
4. Continue with step 7 of the v1_12_04 instructions.

When the transition is complete, these temporary instructions will no longer be necessary and the instructions for art v1_12_04 will again be correct.

What's going on here? The pullProducts system is driven by files, called manifests, that list all of the products needed to create a complete distribution. The pullProducts script parses arguments 2 through 5 to determine which manifest it needs to use. It then fetches the compressed tar files specified in the manifest and unwinds them into the target directory.

For each fully flavor-qualified version of art there are several manifests that are customized for different experiments, or groups of experiments. For example the bare art distributions with no experiment specific extras has art in its name. The one that Mu2e uses has mu2e in its name; this contains the art distribution plus our versions of geant4, scons, heppdt and splines. All of these products are maintained, built and distributed by the art team. As it happens, the mu2e manifest is also used by the muon g-2 experiment. There are also manifests customized for NOvA and for the LArSoft experiments.

Starting with art version v1_15_00 the manifest that is common to both Mu2e and Muon g-2 will simply be called mu.

This frees up the name mu2e for reuse. In the near future there will be a new manifest named mu2e. It will contain the contents of the mu manifest plus additional products that are built by Mu2e; the first of these will be the BaBar tracking code packaged as a UPS product named BTrk.

Lynn plans to make a set of symlinks so that either mu or mu2e will work for distributions between art v1_12_04 and art v1_15_00. As of July 5, 2015 this had not been done.

Cheat Sheet For art v1_12_04 and later

1. The notes provided by SCD are at the following url:
   http://scisoft.fnal.gov/scisoft/bundles/art/v1_12_04/art-v1_12_04.html
   They may help to understand what is happening at each stage of this cheat sheet.
2. Make a top Level directory to hold everything

   cd ${MU2E_TOP}
   

3. Make subdirectories to hold the UPS repository and the magnetic field maps

   mkdir artexternals
   mkdir DataFiles
   

   The following instructions presume that you used exactly these subdirectory names.
4. Download the script that will do the installation of the UPS repository

   mkdir tmp
   cd tmp
   curl -O http://scisoft.fnal.gov/scisoft/bundles/tools/pullProducts
   chmod u+x pullProducts
   

   If curl is not available on your machine, wget may be:

   wget http://scisoft.fnal.gov/scisoft/bundles/tools/pullProducts
   

5. Run the script to install the UPS products:

   ./pullProducts ${MU2E_TOP}/artexternals slf6 mu2e-${ART_VERSION} ${ART_OPTIONS} prof
   

6. If you also want the debug builds of the UPS products, run pullProducts a second time:

   ./pullProducts ${MU2E_TOP}/artexternals slf6 mu2e-${ART_VERSION} ${ART_OPTIONS} debug
   

   The pull Products script is smart enough that it will only copy UPS products that are not already present; for example the Geant4 data files
7. Clean up

   cd ..
   /bin/rm -rf tmp
   

8. Copy the site specific setup script and edit it:

   scp your_kerberos_principal@mu2egpvm01.fnal.gov:/grid/fermiapp/products/mu2e/setupmu2e-art.sh .
   

   Be careful, there is a second argument to scp, a dot, asking scp to copy the requested file into the current directory. Edit the file and replace the definition of MU2E_DATA_PATH with the absolute path to the DataFiles directory created above. The Fermilab setupmu2e-art.sh also ensures that git is available to users; if necessary, replace this with whatever needs to be done at your site to ensure that git is available to users. If you want to run the art workbook at your site, set the 3 workbook-related environment variables to values appropriate for your site.
9. Copy over the Mau9 magnetic field maps. This requires about 4.2GB of disk space.

   mkdir -p DataFiles/BFieldMaps/Mau9
   scp -r mu2egpvm01.fnal.gov:/grid/fermiapp/mu2e/DataFiles/BFieldMaps/Mau9 DataFiles/BFieldMaps/Mau9
   

10. Copy the text files that contain the positions and times of stopped muons; these are used by the old style event generators and will soon be replaced by different files.

    mkdir -p DataFiles/ExampleDataFiles/StoppedMuons
    scp -r mu2egpvm01.fnal.gov:/grid/fermiapp/mu2e/DataFiles/ExampleDataFiles/StoppedMuons DataFiles/ExampleDataFiles/StoppedMuons
    

    You will also need to edit your fcl files to tell the event generators where to find the stopped muon files.
11. When you log in to the machine to work on mu2e, the analog of "setup mu2e" is

     source ${MU2E_TOP}/setupmu2e-art.sh
    

Cheat Sheet for art v1_12_02 only

1. Make a top level directory to hold everything

   cd ${MU2E_TOP}
   

2. Make subdirectories to hold the UPS repository and the magnetic field maps

   mkdir artexternals
   mkdir DataFiles
   

   The following instructions presume that you used exactly these subdirectory names.
3. Download the script that will do the installation of the UPS repository

   mkdir tmp
   cd tmp
   curl -O http://scisoft.fnal.gov/scisoft/projects/art/${ART_VERSION}/pullProducts-${ART_VERSION}
   chmod u+x pullProducts-${ART_VERSION}
   

   If curl is not available on your machine, wget may be:

   wget http://scisoft.fnal.gov/scisoft/projects/art/${ART_VERSION}/pullProducts-${ART_VERSION}
   

4. Run the script to install the UPS products:

   ./pullProducts-${ART_VERSION} ${MU2E_TOP}/artexternals slf6 mu2e ${ART_OPTIONS} prof
   

5. If you also want the debug builds of the UPS products, run pullProducts a second time:

   ./pullProducts-${ART_VERSION} ${MU2E_TOP}/artexternals slf6 mu2e ${ART_OPTIONS} debug
   

   The pull Products script is smart enough that it will only copy UPS products that are not already present; for example the Geant4 data files
6. Clean up

   cd ..
   /bin/rm -rf tmp
   

7. Copy the site specific setup script and edit it:

   scp mu2egpvm01.fnal.gov:/grid/fermiapp/products/mu2e/setupmu2e-art.sh .
   

   Be careful, there is a second argument to scp, a dot, asking scp to copy the requested file into the current directory. Edit the file and replace the definition of MU2E_DATA_PATH with the path to the DataFiles directory created above. The Fermilab setupmu2e-art.sh also ensures that git is available to users; if necessary, replace this with whatever needs to be done at your site to ensure that git is available to users.
8. Copy over the Mau9 magnetic field maps. This requires about 4.2GB of disk space.

   mkdir -p DataFiles/BFieldMaps/Mau9
   scp -r mu2egpvm01.fnal.gov:/grid/fermiapp/mu2e/DataFiles/BFieldMaps/Mau9 DataFiles/BFieldMaps/Mau9
   

9. Copy the text files that contain the positions and times of stopped muons; these are used by the old style event generators and will soon be replaced by different files.

   mkdir -p DataFiles/ExampleDataFiles/StoppedMuons
   scp -r mu2egpvm01.fnal.gov:/grid/fermiapp/mu2e/DataFiles/ExampleDataFiles/StoppedMuons DataFiles/ExampleDataFiles/StoppedMuons
   

   You will also need to edit your fcl files to tell the event generators where to find the stopped muon files.

Security, Privacy, Legal