MadSpin

References

Code/Manual:

Automatic spin-entangled decays of heavy resonances in Monte Carlo simulations
Pierre Artoisenet, Rikkert Frederix, Olivier Mattelaer, Robbert Rietkerk
​http://arxiv.org/abs/arXiv:1212.3460

Code based on the following method:

Angular correlations of lepton pairs from vector boson and top quark decays in Monte Carlo simulations
Stefano Frixione, Eric Laenen, Patrick Motylinski, Brian R. Webber
​http://arxiv.org/abs/hep-ph/0702198

How to run MadSpin in standalone

In standalone, one launches a MadSpin session by typing:

./MadSpin/madspin

This opens a prompt, similar to that of the MadGraph5 Suite. The following commands are then available:

• import FILE:
  imports the LO or NLO lhe file and reads the associated header in order to load relevant information, e.g. the relevant model.
• define LABEL = PART1 PART2 ... :
  allows to define an additional multi-particle tag. The multi-particle tags defined in the header of the file are automatically recognized.
• decay PROCESS:
  specifies the decay branch initiated by an unstable particle to be decayed by MadSpin. Multi-particle tags can be used for the final state particles.
• set OPTION VALUE:
  allows to change some internal options of MadSpin such as the seed or the value of the maximal weight in the unweighting procedure. Type “help options” in the interface for more details on the various available options. (and/or see the list below)
• launch:
  runs MadSpin according to the specified options/decay channels.
• help COMMAND:
  provides detailed information on a specific command.

How to run MadSpin on the flight

MadSpin can also be called directly via the MadEvent/aMC@NLO script (via the launch command or the ./bin/generate_events script). In this case, the script will request some information about the programs to run. For MadEvent the question is:

The following switches determine which programs are run:
 1 Run the pythia shower/hadronization:                   pythia=NOT INSTALLED
 2 Run PGS as detector simulator:                            pgs=NOT INSTALLED
 3 Run Delphes as detector simulator:                    delphes=NOT INSTALLED
 4 Decay particles with the MadSpin module:              madspin=ON
 5 Add weight to events based on coupling parameters:   reweight=OFF
  Either type the switch number (1 to 5) to change its default setting,
  or set any switch explicitly (e.g. type 'madspin=ON' at the prompt)
  Type '0', 'auto', 'done' or just press enter when you are done.
 [0, 4, 5, auto, done, madspin=ON, madspin=OFF, madspin, reweight=ON, ... ][60s to answer]

While for aMC@NLO she is:

The following switches determine which operations are executed:
 1 Perturbative order of the calculation:                              order=NLO
 2 Fixed order (no event generation and no MC@[N]LO matching):   fixed_order=OFF
 3 Shower the generated events:                                       shower=ON
 4 Decay particles with the MadSpin module:                          madspin=ON
  Either type the switch number (1 to 4) to change its default setting,
  or set any switch explicitly (e.g. type 'order=LO' at the prompt)
  Type '0', 'auto', 'done' or just press enter when you are done.
 [0, 1, 2, 3, 4, auto, done, order=LO, order=NLO, ... ][60s to answer] 

In both case, if you can ask to run MadSpin on the flight by typing madspin=ON

The program will propose, in a second step, to edit the madspin_card.dat. This file contains the command lines associated with the MadSpin program that we described in the previous section. Note that MadGraph5 will figure out which event file has to be decayed, so that you do not need to include the “import” command in this file. After these questions have been answered, MadGraph5 proceeds with the Monte Carlo generation:

1. it generates the LHE event file before decay
2. it executes MadSpin
3. if requested, it submits the decayed events to a shower/hadronisation program.

Full list of options

Note some of the options are not in the "help" mention above seems they are not fully secure. They allow much more flexibility but need to be use with great care.

1. import model ModelNane ParamCardPath [--bypass_check]
   Allows to use another model/param_card than the one used for the generation of the events. By default some check are done that the old/new param_card seems compatible but if the optional argument --bypass_check is included.
   New in v2.1.0
2. set ms_dir PATH
   If path doesn't exists, create a directory with all the information that MadSpin needs to decayed events. This stores:
   • The matrix elements
   • The maximal weights
   • The status of the seed (can be changed via the card)
   If path exists, use the information present in that directory which allows to bypass the initialization phase. Note that this is valid only for the SAME param_card. We actually check that this is the case.
3. set BW_effect True|False: [default:True]
   reshuffle the momenta to describe corrrectly the Breit-Wigner of the decayed particle
4. set seed VALUE:
   fix the value of the seed to a given value. By default use the current time to set the seed. random number are generated by the python module random using the Mersenne Twister generator. It has a period of 219937-1.
5. set max_running_process VALUE:
   allow to limit the number of open file used by the code. The number of running is raising like 2*VALUE
   New in v2.0.2