Diagram filters¶

A diagram filter removes Feynman diagrams during the generation of a process. It is a Python function that MadGraph7 calls on every generated diagram:

def remove_diag(diag, model):
    ...

It returns True to remove the diagram and False to keep it. model is the model of the process.

Warning

Removing diagrams usually breaks gauge invariance. The result is then not a physical prediction. Use filters to study subsets of diagrams.

Writing a filter plugin¶

A filter comes from a plugin. A plugin is a Python package in the PLUGIN directory of MadGraph7, or in a MG5aMC_PLUGIN directory on the PYTHONPATH. It provides one filter, assigned to new_diagram_filter in its __init__.py. The filter is selected by the name of the plugin.

For example, PLUGIN/no_photon/__init__.py removes the diagrams with a photon propagator:

# versions of MadGraph7 this plugin works with
minimal_mg7_version = (0, 2, 0)
maximal_mg7_version = (1000, 0, 0)
latest_validated_mg7_version = (0, 2, 1)

def remove_diag(diag, model):
    """Remove the diagrams with a photon propagator."""
    for vertex in diag['vertices'][:-1]:
        # The last leg of a vertex is the propagator to the next vertex.
        # The last vertex closes the diagram and has no propagator.
        if vertex['legs'][-1]['id'] == 22:
            return True
    return False

new_diagram_filter = remove_diag

Every plugin gives the range of MadGraph7 versions it supports with minimal_mg7_version and maximal_mg7_version. latest_validated_mg7_version is optional: MadGraph7 warns when it is more recent than that version. A plugin without the version range is ignored. The minimal_mg5amcnlo_version and maximal_mg5amcnlo_version of MG5_aMC@NLO plugins refer to the MG5_aMC@NLO numbering. A plugin with only those is used without version check, with a warning.

The filter is then used with:

import model sm
generate u u~ > d d~ QED=2 --diagram_filter=no_photon

MadGraph7 reports the number of removed diagrams for each subprocess. display diagrams shows the remaining ones.

The diagram object¶

A tree-level diagram is a list of vertices, diag['vertices']. Each vertex has an interaction id (the id of the model interaction, 0 for the special vertex that closes some diagrams) and a list of legs. A leg has the PDG code id, the number of the external particle (or the smallest external number it combines) and the state (False for an incoming particle). The last leg of a vertex is the propagator that leaves it, except for the last vertex of the diagram.

model.get_particle(pdg) and model.get_interaction(id) give the particle and the interaction behind a PDG code or an interaction id.

Loop diagrams (see below) are LoopDiagram objects. They have the same vertices and also helpers such as diag.get_loop_lines_pdgs(), the PDG codes of the particles in the loop. A filter used at loop level must handle both kinds of diagram.

Selecting the filter¶

The option depends on the kind of generation:

Generation	Option	Filtered diagrams
Tree level, also decay chains and `[treextree]`	`--diagram_filter=NAME`	All the diagrams, both sides of `[treextree]`.
MadLoop, `[virt=QCD]` and loop-induced `[noborn=QCD]`	`--diagram_filter=NAME`	The Born diagrams and the loop diagrams.
NLO with FKS subtraction, `[QCD]`	`--tree_diagram_filter=NAME`	The Born diagrams, the real-emission diagrams, the diagrams of the counterterms and of the electroweak Sudakov amplitudes. They also set the automatic coupling orders.
NLO with FKS subtraction, `[QCD]`	`--loop_diagram_filter=NAME`	The loop diagrams of the virtual corrections.

--diagram_filter is refused for the NLO generation with FKS subtraction. The two options there can be used together, with the same plugin or with two different ones.

NAME is the name of the plugin. Without =NAME, the options use the function remove_diag of PLUGIN/user_filter.py, the older way to define a filter. The options also work with add process.

Things to know¶

NLO real emissions. The FKS subtraction pairs every real-emission diagram in a soft or collinear limit with a Born diagram. A tree filter must keep the real-emission diagrams that match the kept Born diagrams. Otherwise the generation stops with Cannot map born/real configurations.
No Born diagram left. If --tree_diagram_filter removes all the Born diagrams, the generation stops. A [QCD] process that has no Born diagram at all, such as g g > h QED=1 [QCD], is generated in the loop-induced mode. There, use --loop_diagram_filter (or --diagram_filter).
Multicore NLO generation. With low_mem_multicore_nlo_generation, the filter is sent to the worker processes. It must be a function defined at the top level of a module, not a lambda or a nested function.
Coupling orders. At tree level, the automatic coupling orders are determined on the filtered diagrams. Give the orders explicitly if a filter removes the lowest-order diagrams.
Crossing. Processes generated with a filter do not reuse the diagrams of their crossed processes, since a filter does not need to be crossing symmetric.