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_aMC@NLO Suite. The following commands are then available:

command	COMMENT	new in version
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 (but NOT for initial-state, i.e. before the ">" symbol).
decay PROCESS @X	Same as above but all decay with the decay of particle with "X" can not be done with a decay with a different X. This allow syntax for semi-leptonic decay (decay w+ > j j @1; decay w- > e- ve @1; decay w+ > e+ ve @2 ; decay w- > j j @2) (not compatible with spinmode=none/onshell)	experimental in 3.5.0
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 at the same time of the event generation. The typical way to generate_events is via the executable "./bin/generate_events". (Most of the various other method which can be use to generate events are also supported in the same way).

Depending that your process is LO/NLO, you will have a slightly different question: For LO, you will have:

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 NLO it 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 cases, 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.

How to run MadSpin on already generated samples

In addition of the standalone mode describe above. You can run MadSpin on previously generated sample. For this you need to run one of the following executable:

./bin/madevent
./bin/aMC@NLO 

Only one of the two executable is present (depends if you run on a LO process or a NLO process). It opens a shell interface where you can enter

decay_events RUN_XXX

where 'XXX' is your run_number.

Full list of options

Note that some of the options that are not in the "help" mentioned above might lead to unexpected behaviour when not used correctly. They allow for much more flexibility but need to be used 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 it is checked that the old/new param_card are compatible (and if not the code stops), except 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 (and the code checks that this is the case).
3. set seed VALUE:
   Fix the value of the seed to a given value. By default use the current time to set the seed. Random numbers are generated by the python module random using the Mersenne Twister generator. It has a period of 2¹⁹⁹³⁷-1.
4. set Nevents_for_max_weight VALUE:
   number of events for the estimate of the maximum weight needed to perform the reweighting
5. set max_weight_ps_point VALUE:
   number of PS to estimate the maximum weight (for each of the event choose via the previous option)
6. set max_running_process VALUE:
   Allow to limit the number of open processes used by the code. The maximum number of running processes is equal to 2*VALUE.
   New in v2.0.2
7. set onlyhelicity True:
   Activate a mode where no decay is performed but where helicity is assigned to the event (according to the LO matrix-element).New in 2.2.3
8. set spinmode [none|onshell|madspin][default:madspin]
   
   1. madspin default mode with full-spin correlation and off-shell effect
   2. none(new in 2.3) No spin-correlation between production and decay. No off-shell effects. However this mode allows to handle three-body decay and loop induced processes. Due to the lack of spin-correlation it is mainly intended for scalar particle (and in particular the Higgs).
   3. onshell (new in 2.5.3) Keep the full spin-correlation but keep the particle exactly on-shell. Supports three-body decay but not loop-induced processes (in either production or decay). Intended for particle with small width without any two body decay. This mode requires f2py program to be available on your machine.
9. set run_card PATH:
   Only for mode "none" or "onshell". This defines the cut to apply to the 1>N sample. Those cut will be applied in the frame where the particle is at rest. Transverse cut are meaningless in that card and should be kept to zero.
10. set identical_particle_in_prod_and_decay [average|max|crash] [default:average]
    Only for mode "onshell", allow to correctly handle the case where identical are in the production and decay (crash will forbid such situation, average will take the average of all possible permutation of particles and max will take the maximum weight of all the permutation for doing the re-weighting) new in 3.4.0