FAQ-NewPhysics-1: HOWTO.txt

File HOWTO.txt, 5.3 KB (added by anonymous, 7 years ago)
Line 
1********************************************************************************
2*                                                                              *
3*                      h   h  ooo  w     w ttttttt ooo                         *
4*                      h   h o   o w     w    t   o   o                        *
5*                      hhhhh o   o w  w  w    t   o   o                        *
6*                      h   h o   o w  w  w    t   o   o                        *
7*                      h   h  ooo   ww ww     t    ooo                         *
8*                                                                              *
9*                                                                              *
10*                         Use MadGraph's usrmod2...?                           *
11*                                                                              *
12*                            M. Herquet - Nikhef (TH)                          *
13*                                                                              *
14********************************************************************************
15
16IMPORTANT WARNING for users of older usrmod versions: starting with version 2,
17the usrmod script has been deeply redesigned for various reasons (see 'What's
18new ?' below). It is _not_ compatible with the previous usrmod versions, neither
19it is with the former MG model directory structures. It is only compatible with
20the model files produced with or following the conventions of the MG interface
21to the FeynRules Feynman rule generator (see http://feynrules.phys.ucl.ac.be).
22
23Table of contents:
24-----------------
25
26    1) Introduction
27    2) What's new compare to previous versions ?
28    3) Step-by-step how-to
29    4) Advanced tips and tricks
30    5) Parsing library and database format reference
31   
32Introduction
33------------
34This program should be seen as the successor of the original usrmod model written
35by Simon de Visscher in 2006 to deal with user defined MG models using the SM as a
36basis. Thanks to the implementation of new BSM models using the FR package, and to
37the uniformisation of conventions for model files, the usrmod version 2 allows the
38user to start from _any_ existing MG model and to implement (almost) _any_ desired
39change, incl. adding/modifying/removing particles, interactions and external
40parameters.
41
42What's new ?
43------------
44
45Step-by-step how-to
46-------------------
47
48To create a new MG model using usrmod2, all you need is a valid MG model
49(FeynRules format):
50
511) Copy the original model directory to a new location, e.g:
52cp -R my_model new_model
53
542) Go to this model directory, e.g.
55cd new_model
56
573) Create a usrmod "archive" to record the initial state of the model, e.g.
58../usrmod2/usrmod2.py save
59
604) Modify the files:
61particles.dat: to add or remove particles, or to modify particle properties
62interactions.dat: to add or remove interactions, or to modify interactions
63                  properties
64ident_card.dat: to add, remove or modify external parameters read by MG in
65                the param_card.dat
66
675) Use the usrmod "create" mode to create a consistent set of Fortran files
68for your new model:
69../usrmod2/usrmod2.py create
70and give a look to the output to see if it makes sense.
71
726) Edit the coupl_definition??.inc files to modify coupling expressions.
73Definitions of the newly created couplings are all grouped in the last of these
74files.
75
767) Edit the default parameter values in the param_card.dat file
77
788) Type "make testprog" and "./testprog" to test your model compiles properly.
79
809) If you are satisfied with your modifications, save them like in 3). If not,
81go back to 4) (but all changes in 6) and 7) will be lost!). If you want to start
82from a "fresh" copy of the model files, type
83../usrmod2/usrmod2.py restore
84
85Tips and tricks
86---------------
87
88Q: "How to get some extra help ?"
89A: ../usrmod2/usrmod2.py -h
90
91Q: "How to use another model directory than the current path ?"
92A: Use the -p option
93
94Q: "How to save multiple steps during model creation ?"
95A: Use the -f option while saving/creating/restoring to create/use different
96archive files. Beware the size of each of these binary archive file is
97roughly equal to the total size of the model directory!
98
99Q: "How to get more information about what's going one when the script is
100running ?"
101A: Use the -v verbose option, useful for debugging. Always use this when reporting
102a bug.
103
104Q: "How can I add an internal parameter ?"
105A: Simply edit directly the input.inc file and maybe "param_write.inc" if you want
106to see this parameter value in the standard logs. No other file should be modified.
107
108Q: "How can I add a new interaction with an unsupported type, e.g FFFF ?"
109A: Hack manually the _ref_types variable in the Interaction Python class defined
110in the hepobjects module. But be aware that MG/HELAS only supports a limited set of
111Lorentz structure for the interactions.
112
113Q: "Why some interactions/parameters are modified when I only edit the particle
114list ?"
115A: The usrmod2 scripts run many internal consistency checks. For example, a
116particle cannot be added w/o adding the corresponding mass and width parameters,
117if a particle is removed, the associated interactions are also automaticaly
118removed, ... Because of this, modifying one file can have an impact on the
119other ones.
120
121Q: "Who should I congratulate/blame for this wonderful/horrible piece of code ?"
122A: All comments can be sent to mherquet@nikhef.nl
123
124