Mu2e Home
Base and Test Releases
Search
Mu2e@Work

This web page defines the ideas of Base Release and Test Release and discusses how to use them. Some of you may be familiar with a Fermilab product named SRT. While Mu2e does not use SRT, we have borrowed language from SRT; the concepts of Base Release and Test Release have the same meaning as they do in SRT.


Introduction

Prebuilt, ready-to-run releases of the Mu2e Offline software are available in a directory tree rooted at,

 /grid/fermiapp/mu2e/Offline
For example, the release of Offline with the cvs tag v0_3_3 is available at two locations:
 /grid/fermiapp/mu2e/Offline/v0_3_3
 /grid/fermiapp/mu2e/Offline/v0_3_3_SLF5
Under each of these directories you will find all of the header files, all of the .so files and all of the run time configuration files. The first of these directories is built for a 64 bit architecture running SLF4. The second directory is built for a 64 bit architecture running SLF5, such as mu2egpvm02, the GPCF batch nodes and the grid worker nodes.

These are examples of Base Releases: that is, they are prebuilt and ready-to-run. At present all of the .cc files are also present but that may change in the future.

At some time in the future we will make a few changes to this:

You can also build your own base release by checking out all of Offline and building it in the usual way. When the build procedure is complete, you will have a fully functioning base release. The base releases in /grid/fermiapp/mu2e/Offline are made by this way.

There are several things you can do with a base release:

  1. Run mu2e using only files from the base release.
  2. Run mu2e overriding some, or all, of the run time configuration files with local versions.
  3. Checking out a single package from cvs, editing it and building it against a base release.
  4. Creating a new package and building it against a base release.
Doing either of the last two steps involves making and using a test release.

Running Directly from a Base Release

If you want to run a job directly from a base release, you need not checkout any files from cvs. The main use for this pattern is running example code.

> setup mu2e
> source /grid/fermiapp/mu2e/Offline/v0_3_3/setup.sh
> mu2e -c /grid/fermiapp/mu2e/Offline/v0_3_3/Mu2eG4/test/g4test_01.fcl
The first command adds Mu2e site-specific information to your environment and the second command adds release specific information to your enviroment. See also the documentation on the setup files.

A variation on this is that you can copy the .fcl file to your local area and run it from there:

> setup mu2e
> source /grid/fermiapp/mu2e/Offline/v0_3_3/setup.sh
> cp /grid/fermiapp/mu2e/Offline/v0_3_3_SLF5/Mu2eG4/test/g4test_03.fcl myconfig.fcl
  ... edit myconfig.fcl
> mu2e  -c myconfig.fcl
In the editing step you might change the random number seeds, the run number, the names of the input and output files and so on. If you want also to customize such files as geom_01.txt and genconfig_01.txt, read the next section.

This pattern is used, for example, when doing Monte Carlo production on the grid. In the future, when the experiment has many data files, we will use this same patter to run production reconstruction code on those data files.

Making Run-Time Changes to a Base Release

A much more common use case is:

To give a concrete example, suppose that I want to tell the event generator to run the Daya Bay cosmic ray generator and to tell Geant4 to kill low momentum electrons, positrons and photons that are created inside the earthen overburden. In this case I need to make two new files in my local area, mygeom.txt and genDYB.txt:

mygeom.txt:

#include "Mu2eG4/test/geom_01.txt"
bool g4.doCosmicKiller  = true;
int  g4.cosmicKillLevel = 2;
Here the path to geom_01.txt must be specified relative to the root of the base release.

genDYB.txt:

bool   conversionGun.do = false;
bool   cosmicDYB.do     = true;
double cosmicDYB.mean   =  -1;

Then edit myconfig.fcl from the previous section to use these two files in place of geom_01.txt and genconfig_02.txt.

services: {
  user: {
   GeometryService : { inputFile : "mygeom.txt" }
  }
}
physics: {
  producers: {
    generate: {
      module_type   : EventGenerator
      inputfile     : "genDYB.txt"
      seed          : [7789]
    }
  }
}
In this fragment, the two files mygeom.txt and genDYB.txt are both in the current working directory so they must be specified as shown above.

To run mu2e using the above files:

> setup mu2e
> source /grid/fermiapp/mu2e/Offline/v0_3_3_SLF5/setup.sh
> mu2e  -c myconfig.fcl
The third line in this fragment defines tells mu2e that, when it is looking for the geometry file and the generator configuation file (and a few others files) it should first look in the local directory. If it does not the requested file it should look for it relative to the root of the base release.

The short description of what is going on is that the second line above defines the environment variable MU2E_BASE_RELEASE and third line above defines the environment variable MU2E_TEST_RELEASE. These two elements are part of a search path:

export MU2E_SEARCH_PATH=$MU2E_TEST_RELEASE:$MU2E_BASE_RELEASE:$MU2E_DATA_PATH;

The third element is defined when you execute "setup mu2e" but it is not important for this example. The full details can be found in the discussion about file search paths.

The file search path mechanism does NOT work for the names of event-data input files, for which you must specify a full path, either absolute or relative.

Making Test Releases

There are a few other important use cases:

First a big warning. If you plan to checkout a package from cvs, change some header files, and build it against a base release, DO NOT DO IT. Instead you should check out the full Offline software and rebuild it. The issue is that there is no automated way to tell if there are other packages that depend on the header file(s) that you changed; if there are such packages they must be rebuilt but the build system cannot rebuild packages that are not present in your test release.

If you are checking out a package that only has an analyzer module and perhaps a few helper classes/functions used only by that module, then it is safe to use a test release to work on these files. If there is any doubt at all, check out and build the full Offline software.

The main reasons for using a test release is that it is much faster to rebuild a test release than it is to rebuild the full offline software. But there is an intermediate step between the two. Again consider the case that you are working on a package that contains a few modules plus a few helper functions/classes that are only used by those modules. You can check out the full Offline software and do a full build. If you have editted A_module.cc, you can rebuild just that module, plus its dependencies, by:

scons -j 4 lib/libA_module.os
This will also identify helper files that have been editted and which need to be rebuilt. Under most circumstances, this works much faster than rebuilding the full Offline. This method does have some dangers, if you change other files but forget that you have, this may not rebuild everything that it should. It only makes sense if you are working on the module file only.

Making a Test Release Using an Existing cvs Package

The following prescription describes how to setup a test release, using the HelloWorld cvs package as an example. The prescription is based on the scripts developed for the Mu2eSoftware workshop in August. Read the section of the workbook that discusses base releases and test releases.

# cd to a clean working directory

setup mu2e

cvs co Offline/HelloWorld
cd Offline

source path_to_base_release/bin/createTestRelease      # Substitute the path to a real base release.
source setup.sh

# edit HelloWorld_module.cc to change the printout to something different.

scons -j 8
mu2e -c HelloWorld/test/hello.fcl

When you log out and log in again, you reestablish the test release environment by:

setup mu2e
# cd to the same working directory as above
cd Offline
source setup.sh
When you have made changes to your code you can commit it back to cvs. At any time you can cd back to the directory above Offline, check out more packages and build them, with no additional setups or changes. But, if you are changing header files, this is very, very dangerous; in that case we strongly recommend that you checkout and build the full Offline.

Starting a New CVS Package in a Test Release

We do not have the helper scripts written to start a new cvs package. Here is how to do it.

  1. Check out a small subset of Offline. For example,
  2. cd Offline
  3. mkdir -p MyPackage/src
  4. cd MyPackage/src
  5. copy an appropriate SConscript file into MyPackage/src
  6. cd ../..
  7. cvs add MyPackage
  8. cvs add MyPackage/src
  9. cvs add MyPackage/src/SConscript
  10. cvs commit -m "First release." MyPackage
Then you can delete the contents of the working directory and follow the procedure in the previous section to create a test release based on the package you just created. Add the inc and test subdirectories as needed. Add files as needed. For additional information about cvs, see the Mu2e CVS Cheat Sheet.

Making a Test Release For use as a Sandbox

If you want to create a test release for use as a sandbox environment, disconnected from cvs, you can do the following:

# cd to a clean working directory

setup mu2e
source path_to_base_release/bin/createTestRelease      # Substitute the path to a real base release.
source setup.sh

mkdir -p MyPackage/src

# copy an appropriate SConscript file into MyPackage/src
# create some new .cc files in MyPackage/src

scons -j 8

# run mu2e


Fermilab at Work ]  [ Mu2e Home ]  [ Mu2e @ Work ]  [ Mu2e DocDB ]  [ Mu2e Search ]

For web related questions: Mu2eWebMaster@fnal.gov.
For content related questions: kutschke@fnal.gov
This file last modified Sunday, 04-May-2014 12:17:37 CDT
Security, Privacy, Legal Fermi National Accelerator Laboratory