Embedding Procedures

Overview

This document lists the procedures used for requesting embedding, running embedding jobs, and retrieving data. Please note that some steps require privileged accounts.

Embedding Documentation

Overview

The purpose of embedding is to provide physicists with a known; Monte Carlo tracks, where the kinematics and particle type is known exactly, are introduced into the realistic environment seen in the analysis - a real data event. How reconstruction preforms on these "standard candle" tracks provides a baseline which can be used to correct for acceptance and effciency effects in various analyses.

In STAR, embedding is achieved with a set of software tools - Monte Carlo simulation software, as well as the tools for real data event reconstruction - accessed through a suite of scripts. These documents attempt to provide an introduction to the scripts and their use, but the STAR collaborator is referred to the separate web pages maintained for Simulations and Reconstruction for deeper questions of the processes involved in those respective tasks.

Please note, the general procedure for embedding is:

The Physics Working Group Convenor submits an embedding request. The request will be assigned a request number and priority by the Analysis Coordinator, see this page for more information.
The Embedding Coordinator will coordinate the distribution of embedding requests. Users who wish to run their own embedding are encouraged to do so - but it must be verified with the Embedding Coordinator.
The Embedding Coordinator is responsible for the QA of all embedding requests. When the Embedding Coordinator has verified that the test sample produced is acceptable, full production is authorized.

For EC and ED(s) (OBSOLETE)

Embedding instructions for EC and ED(s)

   Last updated on Sept/06/2011 by Christopher Powell

   Current Embedding Coordinator (EC): Xianglei Zhu (zhux@rcf.rhic.bnl.gov)

Current Embedding Deputy (ED):

   Current PDSF Point Of Contact (POC): Jeff Porter (RJPorter@lbl.gov)

   Revised history

Sept/06/2011: Update EC and ED

Nov/17/2010: Added some tickets for the records

Aug/02/2010: Update directory structure for LOG and Generator files

Jun/11/2010: Added approved chains by Lidia

May/29/2010: Modify procedures of 'Production chain options'

May/27/2010: Several minor fixes

May/25/2010: Added 'Production chain options', 'Locations of outputs etc at HPSS'

May/24/2010: Update trigger id options

May/21/2010: Update instructions for xml file, useful discussions

   Contents

Instructions how to set up xml file

Production chain options

Locations of outputs, log files and back up of relevant codes at HPSS

Some useful discussions in hyper-news and bug-report

   Please send me (CBPowell@lbl.gov) an e-mail if you have any questions/suggestions.

Instructions how to set up xml file

The typical xml file for the embedding job submission looks

<!-- Generated by StRoot/macros/embedding/get_embedding_xml.pl on Mon Aug  2 15:26:13 PDT 2010 -->
<?xml version="1.0" encoding="utf-8"?>
<job maxFilesPerProcess="1" fileListSyntax="paths">

<command>
<!-- Load library -->
starver SL07e

<!-- Set tags file directory -->
setenv EMBEDTAGDIR /eliza3/starprod/tags/ppProductionJPsi/P06id

<!-- Set year and day from filename -->
setenv EMYEAR `StRoot/macros/embedding/getYearDayFromFile.pl -y ${FILEBASENAME}`
setenv EMDAY `StRoot/macros/embedding/getYearDayFromFile.pl -d ${FILEBASENAME}`

<!-- Set log files area -->
setenv EMLOGS /project/projectdirs/star/embedding

<!-- Set HPSS outputs/LOG path -->
setenv EMHPSS /nersc/projects/starofl/embedding/ppProductionJPsi/JPsi_&FSET;_20100601/P06id.SL07e/${EMYEAR}/${EMDAY}

<!-- Print out EMYEAR and EMDAY and EMLOGS -->
echo EMYEAR : $EMYEAR
echo EMDAY  : $EMDAY
echo EMLOGS : $EMLOGS
echo EMHPSS : $EMHPSS

<!-- Start job -->
echo 'Executing bfcMixer_TpcSvtSsd(1000, 1, 1, "$INPUTFILE0", "$EMBEDTAGDIR/${FILEBASENAME}.tags.root", 0, 6.0, -1.5, 1.5, -200, 200, 160, 1, triggers, "P08ic", "FlatPt"); ...'

root4star -b &lt;&lt;EOF
  std::vector&lt;Int_t&gt; triggers;
  triggers.push_back(117705);
  triggers.push_back(137705);
  triggers.push_back(117701);
  .L StRoot/macros/embedding/bfcMixer_TpcSvtSsd.C
  bfcMixer_TpcSvtSsd(1000, 1, 1, "$INPUTFILE0", "$EMBEDTAGDIR/${FILEBASENAME}.tags.root", 0, 6.0, -1.5, 1.5, -200, 200, 160, 1, triggers, "P08ic", "FlatPt");
  .q
EOF

ls -la .
cp $EMLOGS/P06id/LOG/$JOBID.log ${FILEBASENAME}.$JOBID.log
cp $EMLOGS/P06id/LOG/$JOBID.elog ${FILEBASENAME}.$JOBID.elog


<!-- New command to organize log files -->
mkdir -p $EMLOGS/P06id/JPsi_20100601/LOG/&FSET;
mv $EMLOGS/P06id/LOG/$JOBID.* $EMLOGS/P06id/JPsi_20100601/LOG/&FSET;/

<!-- Archive in HPSS -->
hsi "mkdir -p $EMHPSS; prompt; cd $EMHPSS; mput *.root; mput ${FILEBASENAME}.$JOBID.log; mput ${FILEBASENAME}.$JOBID.elog"

</command>


<!-- Define locations of log/elog files -->
<stdout URL="file:/project/projectdirs/star/embedding/P06id/LOG/$JOBID.log"/>
<stderr URL="file:/project/projectdirs/star/embedding/P06id/LOG/$JOBID.elog"/>


<!-- Input daq files -->
<input URL="file:/eliza3/starprod/daq/2006/st*"/>

<!-- csh/list files -->
<Generator>
  <Location>/project/projectdirs/star/embedding/P06id/JPsi_20100601/LIST</Location>
</Generator>

<!-- Put any locally-compiled stuffs into a sand-box -->
<SandBox installer="ZIP">
  <Package name="Localmakerlibs">
    <File>file:./.sl44_gcc346/</File>
    <File>file:./StRoot/</File>
    <File>file:./pams/</File>
  </Package>
</SandBox>

</job>

Below is step by step instructions how to set it up for each request.

You can grab some xml files from other requests and modify manually

or can also create it by yourself with "StRoot/macros/embedding/get_embedding_xml.pl".

The option "-h or --help" will show all available options in "get_embedding_xml.pl".

1. Set up daq/tags files

Please contact POC at PDSF to locate daq/tags files if you don't find any daq/tags files

in the eliza disks at PDSF. The relevant descriptions in the xml file are

<!-- Input daq files --> 
<input URL="file:/eliza3/starprod/daq/2006/st*"/>

for daq files and

<!-- Set tags file directory -->
setenv EMBEDTAGDIR /eliza3/starprod/tags/ppProductionJPsi/P06id

for tags files.

You can change the locations of daq/tags files in xml by "-daq [daq file path]" and "-tag [tags file path]" options like

> StRoot/macros/embedding/get_embedding_xml.pl -daq /eliza3/starprod/daq/2006  -tag /eliza3/starprod/tags/ppProductionJPsi/P06id

Note1-1: You can put the options in any order, so the command below gives the same result as above

> StRoot/macros/embedding/get_embedding_xml.pl -tag /eliza3/starprod/tags/ppProductionJPsi/P06id -daq /eliza3/starprod/daq/2006

Note1-2: If you have already created an xml file in your current directory,

"get_embedding_xml.pl" won't overwrite the previous xml file. If you want to overwrite it, put "-f" option.

2. Running job, archive outputs into HPSS

Below is the descriptions to run the job (bfcMixer), save log files, put outputs/logs into HPSS.

<!-- Start job -->
echo 'Executing bfcMixer_TpcSvtSsd(1000, 1, 1, "$INPUTFILE0", "$EMBEDTAGDIR/${FILEBASENAME}.tags.root", 0, 6.0, -1.5, 1.5, -200, 200, 160, 1, triggers, "P08ic", "FlatPt"); ...'

root4star -b &lt;&lt;EOF
  std::vector&lt;Int_t&gt; triggers;
  triggers.push_back(117705);
  triggers.push_back(137705);
  triggers.push_back(117701);
  .L StRoot/macros/embedding/bfcMixer_TpcSvtSsd.C
  bfcMixer_TpcSvtSsd(1000, 1, 1, "$INPUTFILE0", "$EMBEDTAGDIR/${FILEBASENAME}.tags.root", 0, 6.0, -1.5, 1.5, -200, 200, 160, 1, triggers, "P08ic", "FlatPt");
  .q
EOF

ls -la .
cp $EMLOGS/P06id/LOG/$JOBID.log ${FILEBASENAME}.$JOBID.log
cp $EMLOGS/P06id/LOG/$JOBID.elog ${FILEBASENAME}.$JOBID.elog


<!-- New command to organize log files -->
mkdir -p $EMLOGS/P06id/JPsi_20100601/LOG/&FSET;
mv $EMLOGS/P06id/LOG/$JOBID.* $EMLOGS/P06id/JPsi_20100601/LOG/&FSET;/

<!-- Archive in HPSS -->
hsi "mkdir -p $EMHPSS; prompt; cd $EMHPSS; mput *.root; mput ${FILEBASENAME}.$JOBID.log; mput ${FILEBASENAME}.$JOBID.elog"

The default bfcMixer is "StRoot/macros/embedding/bfcMixer_TpcSvtSsd.C".

The bfcMixer can be set by "-mixer [bfcMixer file]"

> StRoot/macros/embedding/get_embedding_xml.pl -mixer StRoot/macros/embedding/bfcMixer_Tpx.C

NOTE2-1: There are three different bfcMixer macros, bfcMixer_Tpx.C, bfcMixer_TpcSvtSsd.C and bfcMixer_TpcOnly.C.

You need to choose the proper bfcMixer macro depending on the Run;

<= Run4 : bfcMixer_TpcOnly.C

Run5 - Run7 : bfcMixer_TpcSvtSsd.C

>= Run8 : bfcMixer_Tpx.C

The library, production tag, trigger setup name and request number can be changed by using the following options;

"-production [production tag]", "-lib [library]", "-r [request number]" and "-trg [trigger setup name]"

> StRoot/macros/embedding/get_embedding_xml.pl -production P06id -lib SL07e -r 20100601 -trg ppProductionJPsi

The default library, production tag, and trigger setup name are SL08c, P08ic, 2007ProductionMinBias respectively

unless otherwise specified. These will be used for the locations of log files, scripts as well as the path in HPSS like

<!-- Load library -->
starver SL07e

...
...

ls -la .
cp $EMLOGS/P06id/LOG/$JOBID.log ${FILEBASENAME}.$JOBID.log
cp $EMLOGS/P06id/LOG/$JOBID.elog ${FILEBASENAME}.$JOBID.elog


<!-- New command to organize log files -->
mkdir -p $EMLOGS/P06id/JPsi_20100601/LOG/&FSET;
mv $EMLOGS/P06id/LOG/$JOBID.* $EMLOGS/P06id/JPsi_20100601/LOG/&FSET;/

<!-- Archive in HPSS -->
hsi "mkdir -p $EMHPSS; prompt; cd $EMHPSS; mput *.root; mput ${FILEBASENAME}.$JOBID.log; mput ${FILEBASENAME}.$JOBID.elog"

...
...

<!-- csh/list files -->
<Generator>
  <Location>/project/projectdirs/star/embedding/P06id/JPsi_20100601/LIST</Location>
</Generator>

NOTE2-2: If the directories "/project/projectdirs/star/embedding/P06id/JPsi_20100601/LIST"

doesn't exist, "get_embedding_xml.pl" will complain and doesn't generate xml like

    Error: No /project/projectdirs/star/embedding/P06id/JPsi_20100601/LIST exists. Stop. 
    Make sure you've put the correct path for generator file.

Currently, I didn't implement to automatically create "LOG" and "LIST" directories

in get_embedding_xml.pl. So you have to make those directories manually.

Please don't forget to make those directories group read/writable. Please contact me

if you are not clear what you should do (Hiroshi).

NOTE2-3: LOG directory structure has been changed to make them search easier,

and final log files will be moved to

 mv $EMLOGS/P06id/LOG/$JOBID.* $EMLOGS/P06id/JPsi_20100601/LOG/&FSET;/

where we have introduced three additional directory "P06id" (production), "JPsi_20100601" (particle name and request id)

and "&FSET" (FSET number, which is determined during the job submission). This directory will be dynamically created

during the job submission, so you don't need to create it.

3. Arguments in the bfcMixer

You can find relevant informations for these numbers in the

STAR simulation request page, http://drupal.star.bnl.gov/STAR/starsimrequest.

Below is an example for the 2006 J/Psi in p + p 200 GeV request

Below is the details how to set each argument in the bfcMixer according to

the informations in the simrequest page

3-1. Particle id and particle name

The particle geantid can be found in "pams/sim/gstar/gstar_part.g".

You can see the J/Psi -> e+e- decay (100% B.R.)

Particle Jpsi       code=160 TrkTyp=4 mass=3.096  charge=0  tlife=7.48e-21,
                      pdg=443  bratio= { 1, }       mode= { 203, }

"code=160" is the geantid for J/Psi so you can set the geantid and particle name by

"-geantid [GEANT3 id]" and "-particle [particle name]"

> StRoot/macros/embedding/get_embedding_xml.pl -geantid 160 -particle JPsi

Please don't put "/" in the particle name. The particle name is also used for the directory

in HPSS as well as in eliza disk to store the outputs. So "/" would be recognized as

directory.

3-2. Particle settings (how to simulate pt distribution)

Particle settings is usually "Flat in pt", generating the flat pt distribution of input MC particles,

which corresponds to the default option "FlatPt" in the last argument of bfcMixer.

There are two other options depending on how to simulate the input MC particles

"Strange" : Smear primary vertices in all (x,y,z) directions with vertex errors stored in tags files

"Spectrum" : Generate transverse momentum by pt*exp(-pt/T) shape, where T is inverse slope parameter

Default T is 0.3 GeV

These options can be changed by "-mode [option]"

> StRoot/macros/embedding/get_embedding_xml.pl -mode Strange

NOTE3-1: The mode option string is case insensitive, so "Strange", "strange", "STRANGE"

or any combination of letters can be accepted as long as it matches with "strange" string.

NOTE3-2: "Strange" option cannot be run in "VFMCE" chain option.

You should disable VFMCE by "-VFMCE" and put the appropriate vertex finder option back to the chain options.

NOTE3-3: "Spectrum" option can only be run after SL08f. We don't have any solutions at this moment except for

doing single MC simulation and embedding, separately.

3-3. Multiplicity

The default multiplicity is 1, i.e. throw 1 input MC particle per event. You can change it by "-mult [multiplicity]"

 > StRoot/macros/embedding/get_embedding_xml.pl -mult 0.05

if the multiplicity is less than 1, the input MC particle will be generated

by the fraction of multiplicity from real data.

The 0.05 gives 5% of multiplicity per event, so the number of particles

will be varied event-by-event depending on the multiplicity.

In the current example, we don't need to modify the multiplicity.

3-4. Primary z-vertex range

The minimum and maximum z-vertex cuts can be set by

"-zmin [Minimum z-vertex value]" and "-zmax [Maximum z-vertex value]"

> StRoot/macros/embedding/get_embedding_xml.pl -zmin -30.0 -zmax 30.0

if PA requests some specific z-vertex cut. The default z-vertex cut is |v_z| < 200 cm.

In the current J/Psi case, we don't need to put any z-vertex cut.

3-5. Rapidity and transverse momentum range

The rapidity and transverse momentum cuts can be set by

"-ymin [Minimum y value]", "-ymax [Maximum y value]",

"-ptmin [Minimum pt value]" and "-ptmax [Maximum pt value]"

> StRoot/macros/embedding/get_embedding_xml.pl -ymin -1.0 -ymax 1.0  -ptmin 0.0  -ptmax 6.0

NOTE3-4: The simulation request shows the eta range, but we'll throw in rapidity instead of eta.

The default rapidity and pt cuts are |y| < 1.5 and 0 < pt < 10 GeV/c, respectively.

For the current example, we only need to modify maximum pt cut off to 6 GeV/c

3-6. Trigger id's

If PA request trigger id(s), you can put them by using "-trigger [trigger id]"

> StRoot/macros/embedding/get_embedding_xml.pl -trigger 117705

you can add multiple triggers by adding more "-trigger [trigger id]" like

> StRoot/macros/embedding/get_embedding_xml.pl -trggier 117705 -trigger 137705 -trigger 117001

minor NOTE3-5: (This doesn't work, please don't try) I had try to implement the "-trigger" argument like

> StRoot/macros/embedding/get_embedding_xml.pl -trigger 117705 137705 ...

to accept multiple numbers with single "-trigger" option, but couldn't succeed with the current

perl version at PDSF/RCF, though it worked with newer perl in my Macbook (Hiroshi).

3-7. Production chain name

In order to use the correct chain option in the bfcMixer, you should set the production chain name like

StRoot/macros/embedding/get_embedding_xml.pl -prodname P06idpp

NOTE3-6: It might not be trivial what kind of chain options are available in the bfxMixer's.

Please take a look at the bfcMixer to make sure that the relevant chain option has been implemented.

Including the all relevant options in get_embedding_xml.pl, the command to produce the J/Psi xml file is

> StRoot/macros/embedding/get_embedding_xml.pl -f -daq /eliza3/starprod/daq/2006 -tag /eliza3/starprod/tags/ppProductionJPsi/P06id \
-production P06id -lib SL07e -r 20100601 -trg ppProductionJPsi -geantid 160 -particle JPsi -ptmax 6.0 -trigger 117705 -trigger 137705 -trigger 117701 \ -prodname P06idpp

There a few additional things we need to modify xml file manually to get the final form shown in the beginning

- First, we also need to set 0 for the 2nd/3rd arguments in the bfcMixer_TpcSvtSsd.C.

Those are flags to turn on SVT (2nd) and SSD (3rd) if they are 1. Since this example is

the request for Run6 p+p, we don't need SVT/SSD and hence must turn them off, i.e. set to be 0.

- Second, 100 % J/Psi -> e+e- has already been implemented in the "pams/sim/gstar/gstar_part.g" and

is available in the default STAR library so we actually don't need to check out pams and recompile.

In that case, you also need to remove "pams" in your "Localmakerlibs".

- Third, PA requests 2 different triggers in "st_jpsi" stream and one trigger in "st_physics" stream

so the xml files should be prepared for those two different streams with different triggers/inputs.

There would be couple of other things we have to do manually, which will depend on each request.

Please let us know your feedback in case you had some special modification on your xml file.

Production chain options

Production chain can be found in http://www.star.bnl.gov/devcgi/dbProdOptionRetrv.pl

Since the current embedding must use "VFMCE" chain option, other vertex finder chain options have to

be excluded. The relevant informations about vertex finder chain options can be found

in "StRoot/StBFChain/BigFullChain.h"

Below is the current procedure how to set up production chain in the bfcMixer's

ED will set up the proper bfcMixer macro with the correct chain options
EC and POC at PDSF will take a look and give feedback
Ask Lidia for her inputs, and verify the new chain with Lidia and Yuri
Enter all chains into Drupal embedding page for documentation
Commit bfcMixer into CVS

Below is the approved chains implemented in the bfcMixer at this moment (Jun/11/2010)

Chains approvied by Lidia

--------------------------------

P07ic CuCu production: TString prodP07icAuAu("P2005b DbV20070518 MakeEvent ITTF ToF ssddat spt SsdIt SvtIt pmdRaw OGridLeak OShortR OSpaceZ2 KeepSvtHit skip1row VFMCE -VFMinuit -hitfilt");

P08ic AuAu production: DbV20080418 B2007g ITTF adcOnly IAna KeepSvtHit VFMCE -hitfilt l3onl emcDY2 fpd ftpc trgd ZDCvtx svtIT ssdIT Corr5 -dstout

If spacecharge and gridleak corrections are on average instead of event by event then Corr5-> Corr4, OGridLeak3D, OSpaceZ2.

P08ie dAu production : DbV20090213 P2008 ITTF OSpaceZ2 OGridLeak3D beamLine, VFMCE TpcClu -VFMinuit -hitfilt

TString chain20pt("NoInput,PrepEmbed,gen_T,geomT,sim_T,trs,-ittf,-tpc_daq,nodefault);

P06id pp production : TString prodP06idpp("DbV20060729 pp2006b ITTF OSpaceZ2 OGridLeak3D VFMCE -VFPPVnoCTB -hitfilt");

P06ie pp production : TString prodP06iepp("DbV20060915 pp2006b ITTF OSpaceZ2 OGridLeak3D VFMCE -VFPPVnoCTB -hitfilt"); run# 7096005-7156040

TString prodP06iepp("DbV20061021 pp2006b ITTF OSpaceZ2 OGridLeak3D VFMCE -VFPPVnoCTB -hitfilt"); run# 7071001-709402

Locations of outputs, log files and back up of relevant codes at HPSS

Current output as well as log file location at HPSS is determined by the following scheme

/nersc/projects/starofl/embedding/${TRGSETUPNAME}/${PARTICLE}_&FSET;_${REAUESTID}/${PRODUCTION}.${LIBRARY}/${EMYEAR}/${EMDAY}

where "&FSET;" is 3 digit number determined at job submission (e.x. 100),

"${TRGSETUPNAME}" is trigger set up name (e.x. 2007ProductionMinBias),

"${PARTICLE}" is input MC particle name (e.x. JPsi),

"${REQUEST}" is the request id assigned for each embedding request,

"${PRODUCTION}" is the production tag for the real data (e.x. P07id),

"${LIBRARY}" is the library used for embedding simulation which is not

always matched with that for the real data production (e.x. SL08f),

"${EMYEAR}" and "${EMDAY}" are year and day number

extracted from the input file

The back up locations of relevant source codes, macros, scripts and xml files are

 (starofl home) /home/starofl/embedding/CODE/${TRGSETUPNAME}/${PARTICLE}_${REQUESTID}/${PRODUCTION}.${LIBRARY}/${EMYEAR}

(HPSS) /nersc/projects/starofl/embedding/CODE/${TRGSETUPNAME}/${PARTICLE}_${REQUESTID}/${PRODUCTION}.${LIBRARY}/${EMYEAR}

Some useful discussions in hyper-news and bug report

1. VFMCE chain option

Relevant discussions about VFMCE chain option can be found in the following links

http://www.star.bnl.gov/rt2/Ticket/Display.html?id=1588

http://www.star.bnl.gov/HyperNews-star/protected/get/starsoft/7839.html

2. Eta dip around eta ~ 0

Relevant discussions about eta dip problem can be found in

http://www.star.bnl.gov/rt2/Ticket/Display.html?id=1568

the bottom line from Yuri was

The problem was in StTrsMaker for two bfc options "TrsPileUp" and "TrsToF"

accounting particle time of flight in producing hits.

The above options activated TPC fiducial volume cut which removed a few cm near

membrane.

The cut has been removed and committed.

Hiroshi has confirmed that with this fix there is no dip at eta ~ 0.

Yuri

3. EmbeddingShortCut chain option

The details can be found in the following ticket in

The bottom line from Yuri was

http://www.star.bnl.gov/rt2/Ticket/Display.html?id=1851

EmbeddingShortCut means that TpcHitMover and dEdx makers
will not apply corrections for simulated data (IdTruth > 0 && IdTruth
< 10000 && QA > 0.95).
Trs has to have it. TrsRS should not have it.
Yuri

and

this option has really started to be used since release SL10c.
Till this release this option was always "ON" by default.
The only need for back propagation is when you will use release >= SL10c
with Trs. This correction will be done in dev for nightly tests.
Yuri

4. Bug in StAssociationMaker

See ticket in

http://www.star.bnl.gov/rt2/Ticket/Display.html?id=2010

For EC and ED(s)