Here are pointers on how to use GeneratorTParticle selected by the option -g tparticle for o2-sim.

Reading TParticle files

The generator GeneratorTParticle can read events from a ROOT file containing a TTree with a branch holding a TClonesArray of TParticle objects. These files can be produced by a standalone event generator program (EG).

To make a simulation reading from the file particles.root, do

o2-sim -g tparticle --configKeyValues "GeneratorFileOrCmd.fileNames=particles.root"  ...

Configurations

The name of the TTree to read can be set by the configuration key GeneratorTParticle.treeName. The default is T
The name of the TBranch holding the TClonesArray of TParticle objects can be set by the configuration key GeneratorTParticle.branchName. The default is Particles

For example

o2-sim -g tparticle --configKeyValues "GeneratorFileOrCmd.fileNames=particles.root;GeneratorTParticle.treeName=Events;GeneratorTParticle.branchName=Tracks"  ...

Reading TParticle events from child process

GeneratorTParticle can not only read events from a file, but can also spawn an child EG to produce events. Suppose we have a program named eg which is some EG that writes TParticle event records to a file . Then we can execute a simulation using this external EG by

o2-sim -g tgenerator --configKeyValues "GeneratorFileOrCmd.cmd=eg"

Configurations

Same as above.

Example EG

The child-process feature allows us to use almost any EG for which we have a TGenerator interface without compiling it in to O2. Suppose we have defined the class MyGenerator to produce events.

class MyGenerator : public TGenerator {
public:
  MyGenerator();
  void Initialize(Long_t   projectile,
                  Long_t   target,
                  Double_t sqrts);
  void GenerateEvent();
  Int_t ImportParticles(TClonesArray* particles,Option_t*option="");
};

and a steering class

struct MySteer {
  TGenerator*   generator;
  TFile*        file;
  TTree*        tree;
  TClonesArray* particle;
  Int_t         flushEvery;
  MySteer(TGenerator* generator,
          const TString& output,
          Int_t flushEvery)
    : generator(generator)
      file(TFile::Open(output,"RECREATE")),
      tree("T","Particle tree"),
      particles(new TClonesArray("TParticle")),
      flushEvery(flushEvery)
  {
    tree->SetDirectory(file);
    tree->Branch("Particles",&particles);
  }
  ~MySteer() { close(); }
  void event() {
    particles->Clear();
    generator->GenerateEvent();
    generator->ImportParticles(particles);
    tree->Fill();
  }
  void sync() {
    tree->AutoSave("SaveSelf FlushBaskets Overwrite");
  }
  void run(Int_t nev) {
     for (Int_t iev = 0; iev < nev; iev++) {
       event();
       if (flushEvery > 0 and (iev % flushEvery == 0) and iev != 0)
         sync();
     }
  }
  void close() {
    if (not file) return;
    file->Write();
    file->Close();
    file = nullptr;
  }
};

Then we could make the script MyEG.macro (complete code) like

void MyEG(Int_t nev,const TString& out,Int_t every=1)
{
  MyGenerator* eg = new MyGenerator();
  eg->Initialize(2212, 2212, 5200);

  MySteer steer(eg, out, every);
  steer.run(nev);
}

and a simple shell-script myeg.sh to pass arguments to the MyEG.macro script

#!/bin/sh

nev=1
out=particles.root

while test $# -gt 0 ; do
    case $1 in
    -n) nev=$2 ; shift ;;
    -o) out=$2 ; shift ;;
    *) ;;
    esac
    shift
done

root -l MyEG.macro -- $nev \"$out\"

We can then do

o2-sim -g tgenerator --configKeyValues "GeneratorFileOrCmd.cmd=./myeg.sh"

to produce events with our generator MyGenerator.

Implementation details

Internally GeneratorTParticle

creates a unique temporary file name in the working directory,
builds a command line, e.g.,

eg options -o temporary-name &
and executes that command line

The future

The GeneratorTParticle (and sister generator GeneratorHepMC) is configured through configuration keys set via --configKeyValues

GeneratorTParticle.treeName=name the name of the TTree in the input files.
GeneratorTParticle.branchName=name the name of the TBranch in the TTree that holds the TClonesArray of TParticle objects.
GeneratorFileOrCmd.fileNames=list a comma separated list of HepMC files to read
GeneratorFileOrCmd.cmd=command line a command line to execute as a background child process. If this is set (not the empty string), then GeneratorFileOrCmd.fileNames is ignored.
A number of keys that specifies the command line option switch that the child program accepts for certain things. If any of these are set to the empty string or special value none, then that switch and corresponding option value is not passed to the child program.
- GeneratorFileOrCmd.outputSwitch=switch (default >) to specify output file. The default of > assumes that the program write events, and only those, to standard output.
- GeneratorFileOrCmd.seedSwitch=switch (default -s) to specify the random number generator seed. The value passed is selected by the o2-sim option --seed.
- GeneratorFileOrCmd.bMaxSwitch=switch (default -b) to specify the upper limit on the impact parameters sampled. The value passed is selected by the o2-sim option --bMax.
- GeneratorFileOrCmd.nEventsSwitch=switch (default -n) to specify the number of events to generate. The value passed is selected by the o2-sim option --nEvents or (-n).
- GeneratorFileOrCmd.backgroundSwitch=switch (default &) to specify how the program is put in the background. Typically this should be &, but a program may itself fork to the background.

The command line build will now be

‍commandLine nEventsSwitch nEvents seedSwitch seed bMaxSwitch bMax outputSwitch output backgroundSwitch

If any of the Switch keys are empty or set to none, then the corresponding option is not propagated to the command line. For example, if bMaxSwitch is empty, then the build command line will be

‍commandLine nEventsSwitch nEvents seedSwitch seed outputSwitch output backgroundSwitch

TODO

Header information

The class GeneratorTParticle will take a key parameter, say headerName which will indicate a branch that contains header information. Under that branch, the class will then search for leaves (TLeaf) that correspond to standard header information keys (see o2::dataformats::MCInfoKeys). If any of those leaves are present, then the corresponding keys will be set on the generated event header.

Thus, as long as the generator observes the convention used, we can also import auxiliary information (impact parameter, Npart, ...) from the input files in addition to the particle information.