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

Any remote site can mount the cvmfs partition over the network and we recommend that you do that rather than using the procedures described here. For policy reasons that may not always be possible, which is why these prodcedures exist. If you choose to use cvmfs, you can size your local cache so that everything you normally use will sit in the cache. Therefore you pay network latency only on the first use of any new ups product; on subsequent uses the products are cached locally. Therefore it is possible to work on your laptop even when it is not connected to a network.

These instructions explain what you must install in order to run the Mu2e introductory examples. If you wish to do other work, you may also need to download the appropriate event-data input files and appropriate run-time configuration files.

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
• Cheat Sheet for art v1_17_07
• An older version of this file, for archival purposes

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).

Starting with OSX 10.11, El Kapitan, Apple made some security changes referred to as SIP; this also affects OSX 10.12, Sierra. A lot of our software will not work on machines that have SIP enabled; more information is available on the Mu2e page about SIP on MAC OS El Kapitan and above.

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. Some users have reported success using SLF binaries on other Redhat based linux versions, such as Fedora.

The art team supports Ubuntu14.04 and will soon support Ubuntu16; they plan to discontinue support for Ubuntu14.04 soon after Ubuntu16 support is available; there will likely be one release of art with support for both versions of Unbuntu.

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, d13 or d14.
3. Decide on which art version you wish to install, for example

   export ART_VERSION=v1_17_07
   

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

   export ART_OPTIONS=s30-e9
   

   See the table below to learn which ART_OPTIONS are required/allowed for which ART_VERSION.
5. Learn the correct version of the BTrk tracking code to use. You can learn this by looking at Offline/setup.sh. At this writing the correct version is:

   export BTRK_VERSION=v1_01_01
   

The art team maintains a page that describes the art options. The two options shown in the above example are e9 and s30; 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, ART_OPTIONS and BTRK_VERSION for all versions of art that have been used by Mu2e, starting from art v1_12_04.

Mu2e has not used every version of art; normally we jump to the most recent version when it has a feature we need or when we have a lull in other computing work.

Cheat Sheet for art v1_17_07

To pull products for a different version of art, use the following as a model but consult the table above for the appropriate values of version numbers and qualifiers.

1. The notes provided by SCD are at the following url:
   http://scisoft.fnal.gov/scisoft/bundles/art/v1_12_07/art-v1_17_07.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 and that you defined the environment variables described in Collecting Information.
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 mu-${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 mu-${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. Copy the BTrk ups product. This is not yet managed by pull products.

   scp your_kerberos_principle@mu2egpvm01.fnal.gov:/grid/fermiapp/products/mu2e/Downloads/BTrk_${BTRK_VERSION}.tar.gz .
   cd ../artexternals
   tar xzf ../tmp/BTrk_${BTRK_VERSION}.tar.gz
   

8. Clean up

   cd ..
   /bin/rm -rf tmp
   

9. 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. Make the following edits to this file:
   • Redefine MU2E_DATA_PATH with the absolute path to the DataFiles directory created above.
   • setupmu2e-art.sh ensures that git is available to users. If your system does not automatically provide git in a users environment you may wish to modify setupmu2e-art.sh so that git is available to all users that source this script.
   • If you want to run the art workbook at your site, set the 3 workbook-related environment variables. to values appropriate for your site. The variables are:

     export ART_WORKBOOK_OUTPUT_BASE=/mu2e/data/users
     export ART_WORKBOOK_WORKING_BASE=/mu2e/app/users
     export ART_WORKBOOK_QUAL="s3:e5"
     

10. Copy over the GA05 magnetic field maps. This requires about 4.2GB of disk space for the B fields and 2.4GB for the CRV lookup tables.

    mkdir -p DataFiles/BFieldMaps
    scp -r your_kerberos_principle@mu2egpvm01.fnal.gov:/cvmfs/mu2e.opensciencegrid.org/DataFiles/BFieldMaps/GA05 DataFiles/BFieldMaps
    mkdir -p DataFiles/CRVConditions
    scp -r your_kerberos_principle@mu2egpvm01.fnal.gov:/cvmfs/mu2e.opensciencegrid.org/DataFiles/CRVConditions/v2_0 DataFiles/CRVConditions
    

11. 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.

    scp -r mu2egpvm01.fnal.gov:/cvmfs/mu2e.opensciencegrid.org/DataFiles/mergedMuonStops DataFiles
    

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

     source ${MU2E_TOP}/setupmu2e-art.sh
    

Security, Privacy, Legal