- Table of contents
- The experiment environment setup script
- Experiment-specific hooks
The experiment environment setup script¶
Every experiment has a script for initializing its standard software environment, which users source from a standard place. This script may do any or all of the following things.
- Initialize ups products system and products areas.
- Set up some basic ups products.
- Set environment variables.
This section explains the recommended way of writing this script.
Initializing ups¶
After initializing ups, the following should be the case:
- The executable
ups
should be on the execution path. - Command or alias
setup
should be defined. - The products path (environment variable
PRODUCTS
) should be defined as a colon-separated list of ups products areas.
With respect to the last point, the products path may include the following ups products areas (in order).
- Experiment-specific products (e.g.
/grid/fermiapp/products/uboone
). - Larsoft products (for larsoft experiments, e.g.
/grid/fermiapp/products/larsoft
). - Fermilab common products (e.g.
/grid/fermiapp/products/common/db
).
Generally, ups is initialized by sourcing a script called "setups
" (or "setups.sh
" or "setups.csh
", the name can vary) from some standard place. It is acceptable to source multiple "setups
" scripts from multiple products areas, as well as extending the products path to include additional products areas manually.
For larsoft experiments on nodes where the /grid/fermiapp
filesystem is mounted, the main setups
file path is /grid/fermiapp/products/larsoft/setups
.
When initializing ups from the oasis cvmfs products area, the main larsoft setups
file path is /cvmfs/oasis.opensciencegrid.org/fermilab/products/larsoft/setups.for.cvmfs
.
Ups products setup¶
The experiment setup script may set up some basic ups products. Any ups product that is setup in the experiment setup script should be setup as a "current" version. Any product that requires a numbered version or qualifier in the setup command should not be setup in the experiment setup script. Microboone's experiment script sets up the following products that are used by the build environment.
- git
- gitflow
- mrb
Environment variables¶
Here are some environment variables that must or can be set.
- MRB_PROJECT - should be set as "larsoft" for larsoft experiments that use mrb.
- FW_SEARCH_PATH - Art framework file search path.
The standard experiment name may be defined in several different environment variables.
- EXPERIMENT - Used by
ifdh
. - SAM_EXPERIMENT - Used by
sam
. - JOBSUB_GROUP - Used by
jobsub_client
.
Experiment-specific hooks¶
Project.py
is an executable python script. Some functionality of project.py
is implemented in a python module called project_utilities
, which module can be found in subdirectory python
of ups product larbatch
. Module project_utilities
is on the python path when you setup larbatch
. The last statement of project_utilities.py
is
from experiment_utilities import *
This statement allows experiment_utilities
to override any object or function defined in project_utilities
. The intention is that each experiment will have its own version of experiment_utilities
available on the python path.
There are several functions defined in project_utilities
that are candidates for being overridden by experiment_utilities
. Some functions must be overridden for corresponding functionality to be available. Some functions have a default implementation that can be optionally overridden.
Here are some of the functions that can or must be overriden:
get_experiment()
Returns the standard experiment name. The default implementation inproject_utilities
, which should be acceptable in many cases, determines the experiment name using environment variables.
get_setup_script()
Returns the full path of the experiment initialization script on the current node. The default implementation inproject_utilities
raises an exception. This is the only function that absolutely must be overridden to submit batch jobs.
get_ups_products()
Returns a string containing a comma-separated list of top-level ups run-time products. The default implementation inproject_utilities
, which should be acceptable for many larsoft experiments, returns the experiment name + 'code'.
get_role()
Returns a string containing the user's voms role. This function has a default implementation inproject_utilities
that will usually return 'Analysis' or 'Production' depending on the user name.
The following functions are related to SAM data handling system.
get_dropbox(filename)
Returns the full path of the File Transfer Service dropbox corresponding to a file that has metadata in sam. The default implementation inproject_utilities
raises an exception.
get_bluearc_server()
Returns the fictitious sam bluearc server nodename (used for specifying sam locations of files on bluearc). The default implementation inproject_utilities
returns the string containing the experiment name + 'data:'.
get_dcache_server()
Returns the fictitious sam dCache server nodename (used for specifying sam locations of files on dCache). The default implementation inproject_utilities
returns the string 'fnal-dcache:'.
get_sam_metadata(project, stage)
Returns a string containing an fcl fragment for generating sam metadata. The default implementation inproject_utilities
returns an empty string. Jobs submitted using the default implementation will not crash, but will not have any sam metadata. The arguments are python class objects of types ProjectDef and StageDef (defined in larbatch/python).
get_dimensions(project, stage)
Returns a string containing a sam query predicate for querying files generated by the specified project and stage. The default implementation inproject_utilities
raises an exception. The arguments are python class objects of types ProjectDef and StageDef (defined in larbatch/python).