This instruction is a guidance of HFT simulation using STAR Geant and software.

Some of the early examples are developed under DEV library, later tests are under fixed SL14h library. The latter is recommended.

1) Produce fz/fzd input files

a) Single particle
code example: /star/u/yfzhang/lbl/hft/HFT_simu/single/kaonexp/
main scripts: phase_gen.kumac, phase_gen.tcsh, fz_particle.csh
Geometry tag: y2014

The input evcard is based on starsim recognizable format and generated in txt with vertex information and particle GeantID and four momenta, which can be found at event/card/, this is only for sampling more physical pT shape of the particles. In this example, an exponential with slope = 1 was used.
For flat pT, there is no input card, one can only change this line using gkine, see example at:
/star/u/yfzhang/lbl/hft/HFT_simu/single/pion/phase_gen.kumac

phase_gen.tcsh is the script to initialize the input, output and run command for phase_gen.kumac.
fz_particle.csh is the script to run phase_gen.tcsh

runAll.sh and run.con are the scripts to submit condor batch jobs. The simple command is:

>  ./runAll.sh [par] [index_begin] [index_end]

If you want to submit jobs for pion with index 0, 1, ..., 9, then you do ./runAll.sh pion 0 9

Pay attention to the paths of input and output. The generated fz files will be found at events/fz/ as well as the log files.

b) Generate Hijing fz files
Code example: /star/u/yfzhang/lbl/hft/HFT_simu/test_hj/hj_mb/gen/
main macro: starsim.hijing.C
run.sh is the script to run starsim.hijing.C with 10 events each job.
submit.sh and submit.xml under submit/ directory are used to submit scheduler jobs, The simple command is:

>  ./submit.sh [index_begin] [index_end]

The example is for Hijing MB with vertex from -5 to 5, this can be changed in starsim.hijing.C if necessary. e.g. one can change the impact parameter from 0-3 fm for central events.
The generated log files will be at log/ directory and output files will be at out/ directory.

There is another example to generate Hijing fz files based on input nt files.
The example can be found at: /star/u/yfzhang/lbl/hft/HFT_simu/test_hj/hj/
The main scripts are: fz_hijing.csh, hijing.kumac
The script to submit jobs: runAll.sh. The simple command is:

>  ./runAll.sh hijing [index_begin] [index_end]

c) Generate dzero particle fz files
Note: This is the old method which used the kumac to generate signal particles, this does not work with new framework. Suggest to use new method, see Section e).
Code example: /star/u/yfzhang/lbl/hft/HFT_simu/test_hj/hj/
Similar as a), but need local gstar_part.g file to initialize the D0 decay mode, the example is for D0 100% decay to K- and pi+. The GeantId for D0 is defined as 37.
If one want to generate dzero particles originating from the Hijing event vertices, one need extract vertices from Hijing events at first.
The scripts used are zxtract.tcsh and zxtract.kumac

>  ./runvx.sh [index_begin] [index_end]

$zfile is the input Hijing fz file and $vertex_file is the output vertex information at events/vtx/

Then the second step is to generate dzero particles using phase_gen.kumac and phase_gen.tcsh, the running script is fz_dzero.csh. The simple command is:

>  ./runAll.sh dzero [index_begin] [index_end]

The output dzero fz files can be found at events/dzero/fz/

d) Mix dzero particle into Hijing background
Code example: /star/u/yfzhang/lbl/hft/HFT_simu/test_hj/hj/
Main scripts: mix.kumac, fz_mix.csh
Job submit: runAllmix.sh

>  ./runAllmix.sh [bg_basename] [sig_basename] [index_begin] [index_end]

In this example, ./runAllmix.sh hijing382 dzero [index_begin] [index_end]

The output mixed files can be found at events/dzero/mix/
Pay attention to the file size, it should be comparable with and slightly larger than hijing background fz file, but much larger than dzero fz file. If it is not the case, then something could be wrong.

The other issue is one can mix dzero fz generate from kumac with Hijing fzd files generated from starsim.hijing.C, but when going through bfc, the dzero will be separately treated from the background. This is the same as single dzero simulation without any background and one expect very good performance and much higher efficiency due to very small track density.
So mixing dzero fz with Hijing fz files both generated from kumac is strongly suggested. See the comparison of number of TPC hits for these two cases below:

e) New method to generate Hijing + D0 with one starsim macro
Code example: /star/u/yfzhang/lbl/hft/HFT_simu/test_hj/hj_mb/dzero/
Main macro: starsim.hijing.D0.C
Job submit: /submit/submit.sh
Usage:

> cd submit >  ./submit.sh [index_begin] [index_end]

This method is similar as b) generating Hijing events with starsim.hijing.C, however, in the mean time, the MC D0 particles are also generated with Hijing events as defined in the macro.
One can define the pT and rapidity distributions by modifying the ptDist and yDist functions in the macro.
Or sampling flat distributions using kinematics->Kine() instead of kinematics->Dist().
If need add in new defined particles, one need check out pams/sim/gstar/gstar_part.g to local and modify this file accordingly. 
 

2) Tracking and recontruction using bfc

Code example: /star/u/yfzhang/lbl/hft/HFT_simu/CD4/Sti_4/
Default settings: /star/u/yfzhang/lbl/hft/HFT_simu/test_hj/hj_mb_pileup/
Follow Dmitry 's instruction to setup: http://www.star.bnl.gov/cgi-bin/protected/cvsweb.cgi/offline/hft/README.md
Local code directories needed: StRoot, StarDb, offline, pileup
Note that the pixel codes are in library, thus there is no local code needed. This may changed once IST and SSD codes are ready in the library.
In this example there is no SSD included.
For the example with SSD, see /star/u/yfzhang/lbl/hft/HFT_simu/CD4/Sti_4SSD/, with local SSD code.
After check out those code from CVS and patched, one can compile the code with command 'cons'.
The tracking parameters and hit errors are defined under StarDb/Calibration/tracker/
The script runReco.csh is to run bfc chain with pileup adder, the pileup hits input files are under pileup/ directory. The chain options in this script is recommended.
The input files can be fz or fzd files generated in 1).
One can submit jobs under submit/ by

>  ./submit.sh [index_begin] [index_end]

The tracking tuning for Sti_4 is using narrower hit searching window and avoids those low quality or low pT tracks to pick up hft hits. Need include the modified StRoot/Sti/StiKalmanTrackFinder.cxx by Xin, see line 651-667. 

Pay attention to load correct parameters and hit errors by checking log files.
e.g. 

The suggested setting is row.minSearch = .01; // Minimum Search Window ; row.maxSearch = .5; // Maximum Search Window ; row.scaling = 3.; // Search Window Scaling ; row.maxChi2 = 20.; // Max Chi2 ;

To check if the pileup hits are loaded, one need find in log file:
StPxlSimMaker:INFO - StPxlPileupAdder: adding 11982 pileup hits. Number of hits before adding...1641 Number of hits after adding...13623
This reasonably indicates that pileup hits are correctly added.

To check if the detector geometry and are included and activated, one can check:

This is a correct example that PXL hits errors are 12 micron in x and 12 micron in z.  e.g. sqrt(1.44e-06).

This is a correct example that IST hits errors are 170 micron in x and 1700 micron in z. 

3) Analysis
The files *.geant.root and *.event.root generated from 2) are used for further analysis under ntuple/ directory.
The main code is StRoot/StAnaSimMaker, which produce a tree file stored all necessary information for analysis.
need 'cons' to compile the code. 
The main macro is runSim.C
Submit jobs under submit/ by

>  ./submit.sh [index_begin] [index_end]

The output is under out/ namely *.rectree.root.