New event generators are now being implemented in a C++ framework, enabling us to run simulations within the standard STAR, ROOT-based production chain.  Running these generators requires us to migrate away from the familiar starsim interface and begin running simulations in root4star.  Several example macros have been implemented, showing how to run various event generators and how to produce samples of specific particles.  This HOWTO guide illustrates one of these examples.

First, obtain the example macro by checking it out from cvs:

$ cvs co StRoot/StarGenerator/macros
$ cp StRoot/StarGenerator/macros/starsim.kinematics.C .

Running the macro is straightforward.  To generate 100 events, simply do...

$ root4star
root [0] .L starsim.kinematics.C
root [1] int nevents = 100
root [2] starsim(nevents)

This will create an "fzd" file, which can be analyzed with the bfc.C macro as you normally would.

If you're happy with 9 muons per event, thrown with a funky pT and eta distribution, run with the 20012 geometry... then you can use the macro as is.  Otherwise, you'll want to modify things to suit your needs.  Open the macro in your favorite editor (i.e. emacs or vi).  In the "starsim" function, somewhere around line 108, you should see the following lines:

  geometry("y2012");
  command("gkine -4 0");
  command("gfile o pythia6.starsim.fzd");

If you're familiar with the starsim interface, you probably recognize the arguements to the command function.  These are KUIP commands used to steer the starsim application.  You can use the gfile command to set the name of the output file, for example.  The "gkine -4 0" command tells starsim how it should get the particles from the event generator (this shouldn't be changed.)  Finally, the geometry function defined in the macro allows you to set the geometry tag you wish to simulate.  It is the equivalent of the "DETP geom" command in starsim.  So you may also pass magnetic field, switch on/off hadronic interactions, etc.  Any command which can be executed in starsim can be executed using the "command" function.  This enables full control of the physical model, the ability to print out hits, materials, etc... and setup p

Let's take a quick look at the "KINE" event generator and how to configure it.  StarKinematics is a special event generator, allowing us to inject particles into the simulation on an event-by-event basis during a simulation run.  The "trig" function in this macro loops over a requested number of events, and pushes particles.  Let's take a look a this function.
 

void trig( Int_t n=1 )
{
  for ( Int_t i=0; i<n; i++ ) {

    // Clear the chain from the previous event
    chain->Clear();

    // Generate 1 muon in the FGT range
    kinematics->Kine( 1, "mu-", 10.0, 50.0, 1.0, 2.0 );

    // Generate 4 muons flat in pT and eta 
    kinematics->Kine(4, "mu+", 0., 5., -0.8, +0.8 );

    // Generate 4 muons according to a PT and ETA distribution
    kinematics->Dist(4, "mu-", ptDist, etaDist );

    // Generate the event
    chain->Make();

    // Print the event
    primary->event()->Print();
  }
}

The "kinematics" is a pointer to a StarKinematics object. There are three functions of interest to us:

• Kine -- Throws N particles of specified type flat in pT, eta and phi
• Dist -- Throws N particles of specified type according to a pT and eta distribution (and optionally phi distribution) defined in a TF1.
• AddParticle -- Creates a new particles and returns a pointer to it.  You're responsible for setting the identity and kinematics (px, py, pz, etc...) of the particle.

In the example macro, we generate a single muon thrown flat in pT from 10 to 50 GeV, and 1 < eta < 2.  We add to that 4 muons thrown flat 0 < pT < 5 GeV  and |eta|<0.8.  And 4 more muons according to pT and eta distributions defined elsewhere in the code.  After calling "Make" on the big full chain, we print out the resulting event.

Example event record --

[   0|   0|  -1] id=         0    Rootino stat=-201 p=(   0.000,   0.000,   0.000,   0.000;  510.000) v=(  0.0000,  0.0000,   0.000) [0 0] [0 0]
[   1|   1|   1] id=        13        mu- stat=01 p=(  36.421,  -7.940,  53.950,  65.576;    0.106) v=(  0.0181, -0.0905,  26.381) [0 0] [0 0]
[   2|   2|   2] id=       -13        mu+ stat=01 p=(  -2.836,   3.258,   0.225,   4.326;    0.106) v=(  0.0181, -0.0905,  26.381) [0 0] [0 0]
[   3|   3|   3] id=       -13        mu+ stat=01 p=(  -1.159,  -4.437,  -2.044,   5.022;    0.106) v=(  0.0181, -0.0905,  26.381) [0 0] [0 0]
[   4|   4|   4] id=       -13        mu+ stat=01 p=(  -0.091,   1.695,  -0.131,   1.706;    0.106) v=(  0.0181, -0.0905,  26.381) [0 0] [0 0]
[   5|   5|   5] id=       -13        mu+ stat=01 p=(   1.844,  -0.444,   0.345,   1.931;    0.106) v=(  0.0181, -0.0905,  26.381) [0 0] [0 0]
[   6|   6|   6] id=        13        mu- stat=01 p=(   4.228,  -4.467,  -3.474,   7.065;    0.106) v=(  0.0181, -0.0905,  26.381) [0 0] [0 0]
[   7|   7|   7] id=        13        mu- stat=01 p=(  -0.432,  -0.657,   0.611,   1.002;    0.106) v=(  0.0181, -0.0905,  26.381) [0 0] [0 0]
[   8|   8|   8] id=        13        mu- stat=01 p=(  -0.633,  -0.295,  -0.017,   0.706;    0.106) v=(  0.0181, -0.0905,  26.381) [0 0] [0 0]
[   9|   9|   9] id=        13        mu- stat=01 p=(   2.767,   0.517,   1.126,   3.034;    0.106) v=(  0.0181, -0.0905,  26.381) [0 0] [0 0]

The printout above illustrates the STAR event record.  Each row denotes a particle in the simulation.  The 0th entry (and any entry with a status code -201) is used to carry summary information about the configuration of the event generator.  Multiple event generators can be run in the same simulation, and a Rootino is introduced into the event record to summarize their configuration.  The three columns at the left hold the primary event id, the generator event id, and the idtruth id.  The next column shows the PDG id of the particle, followed by the particle's name.  The particle's staus code is next, followed by the 4-momentum and mass, and the particle's start vertex.  Finally, the last four columns denote the primary ids of the 1st and last mother particle and the 1st and last daughter particle.

The STAR event record is saved in a ROOT file at the end of the simulation run, allowing you to read back both particle-wise and event-wise information stored from the event generator and compare with reconstructed events.  Here, the idtruth    ID of the particle is useful, as it allows you to compare reconstructed tracks and hits with the particle which generated them.