User Tips for Running SAM

To start using the SAM system, you must be a registered user.

• To register, fill in the SAM AutoRegistration Form.

This gives basic instructions for users who want to start using SAM with any D0 general framework package. YY is the base release version you want to use. Running with SAM on d0mino:

1. Setup the environment:

      > setup n32
      > setenv SAM_STATION central-analysis
      > setup D0RunII t00.YY.00
      > setup sam
   

2. Create a Dataset Definition, using one of the alternative tools:
   • Create a dataset definition using the SAM Dataset Definition Web Interface.

     A quick "how-to" is included here, or full instructions are available on the interface itself.

     When using the web tool to create a dataset definition, you begin by entering the descriptive information about your dataset. Enter a name for the new definition, your username and group name, and a description which will help you and others remember the reason for this definition. You may also enter keywords to help you find this definition later.

     Next, you will select the dimensions which define your dataset definition. A dimension is simply an attributes in the meta-data that you want to use for finding data files. For each dimension you select, enter a constraint to limit the resulting set of files your definition finds. You can enter a simple set of conditions using the pull-down fields available in the Simple Query entry portion of the web interface. If you need to enter more complex conditions, such as multi-level paranthetically grouped conditions, you can enter them directly in the Free Format section of the web interface. Or, you can even enter a few simple conditions, then use the Copy button to move them down into the Free Format field and then edit them to create your more complex, free-format condition.

     When your dimensions and constraints are entered, you will want to use the Translate Constraints button to determine the set of files that your definition would produce if run as a project right now. If you are satifisfied with your conditions and the resulting file set, you can use the Save button to save your definition for later use in running a project. Or, you can adjust the dimension/constraint values as needed and redo the Translate Constraints operation until you are satisfied with the resulting dataset.

   • Creating a project using the UNIX command line (d0mino) works if one does setup D0RunII t00.YY.00 then setup sam. It won't work if it the setups are done the other way around.

     The command line allows you to specify the same dimensions and constraints that you would using the web interface. You can enter them in one of two ways. You can use the original method, which allowed for the entry of a limited set of dimensions which are combined with a simple AND operator. Or, you can enter the dimensions using the new --dim syntax, which allows you to use any of the 3 operators (AND, OR, MINUS), and to group them paranthetically. This provides the same flexibility of the free-format entry field in the web interface. Examples of one query entered in both styles are included below:

     d0mino> sam translate constraints --filename="%zee%mb1.1av%reco%" --datatier=reconstructed

     d0mino> sam translate constraints --dim="file_name %zee%mb1.1av%reco% and data_tier reconstructed"

     Note the use of the translate constraints command in the above examples. This command is very useful in checking the validity of your constraints before creating your dataset definition. It will return a complete listing of all the files that it finds for your constraints. Then, if you are satisfied with your conditions, you can create a dataset definition that you will use when running your project. You can create the dataset definition using the define dataset command as shown in these two examples:

     d0mino> sam define dataset --group=test --defname=samtest_YOURNAME_zee --filename="%zee%mb1.1av%reco%" --datatier=reconstructed

     d0mino> sam define dataset --group=test --defname=samtest_YOURNAME_zee --dim="file_name %zee%mb1.1av%reco% and data_tier reconstructed"

3. Skip this step if you are ready to link and re-compile your executable.
   Go to your work directory. The newrel command below will create a subdirectory tYY and where YOURPACKAGE is the name of your package.

   > newrel -t t00.YY.00 tYY
   > cd tYY
   > addpgk YOURPACKAGE
   

4. Before linking, you need to do the following:
   NOTE: You may want to update OBJECTS, LIBRARIES, Sam.rcp and YOURMAIN.rcp in cvs to include SAM from now on. This way, you do not have to keep doing this for each release version!

     > emacs YOURPACKAGE/bin/OBJECTS        --> include RegSAMManager in the
                                            --> list of objects.
   
     > emacs YOURPACKAGE/bin/LIBRARIES      --> include sam_manager in the list
                                            --> of libraries.
   
     > emacs YOURPACKAGE/rcp/ReadEvent.rcp  --> comment out the string InputFile
                                            --> line and type the following:
   
                                                string InputFile = "SAMInput:"
   
     > emacs YOURPACKAGE/bin/YOURMAIN.rcp   --> include sam FIRST in the list of
                                                packages you are using:
   
                                                string Packages = "sam YOURSTUFF"
   
                                            --> and add the RCP
     
                                                RCP sam = <YOURPACKAGE Sam>
   
     > emacs YOURPACKAGE/rcp/Sam.rcp        --> define variables needed by SAM
   
       string PackageName="SAMManager"
       string WorkingGroup="test"
       string ApplicationName="d0reco"
       string ApplicationVersion="preco03.05"
       string FileStoreLocation="/pnfs/sam/mammoth/mcc99/"
   
       int FileRequestTimeOut=60  //in minutes; default 0 (indefinite)
       int StoreRequestTimeOut=60  //in minutes; default 0 (indefinite)
   

5. Link the executable:

     > d0setwa
     > gmake YOURPACKAGE.lib
     > gmake YOURPACKAGE.bin
   

6. Create a script to run the executable:

     > cd YOURPACKAGE/bin/
     > d0setwa
   
     > cp ~roco/sam.bash .
     > emacs sam.bash                       --> change defname to the one you
                                                created earlier:
   
                                              --defname=samtest_YOURNAME_zee
   
                                            --> change the executable area from
                                            --> /prj_root/777/alg_5/roco/samtest/
                                            --> to your work area location
   
   

7. You are now ready to run your executable... Execute your script using a small number of test events. You can change int NumEvents = 10 in YOURPACKAGE/rcp/ReadEvent.rcp for testing purposes.

   NOTE: The script sam.bash can be used to read the (temporarily) cached files for reco certification. It can be modified to use the robot tapes by simply removing

     --preferred-loc=/sam/cache