MadGraph signal generation

MadGraph is the principal event-generation workflow documented for the public release. For each model point, SET-ANUBIS constructs the text inputs that define the hard process, collider configuration, model parameters, LLP decay chain and optional shower stage. Keeping these inputs explicit is essential: the cards are part of the scientific definition of the generated sample and therefore part of its provenance.

Role of the generator stage

For an HNL-like benchmark, the generated sample is determined by several linked inputs:

  • the UFO model, which specifies particles, parameters and interactions;

  • the process definition, which selects the production mode;

  • the parameter card, which fixes or scans masses, mixings and widths;

  • the run card, which defines beam conditions, statistics and generator options;

  • the MadSpin card, which specifies parton-level decay chains;

  • the shower card, which configures optional showering and hadronisation.

SET-ANUBIS separates card construction from execution. The same card strings can be inspected locally, stored in the event database, submitted to a local MadGraph installation, executed in a Docker container or passed to a batch system.

HNL card-generation example

The example below prepares an associated-production scan without launching MadGraph.

from setanubis import (
    SetAnubisInterface,
    MadGraphCommandConfig,
    GeneralCardInterface,
    ufo_path,
)

model = SetAnubisInterface(str(ufo_path("UFO_HNL")))

config = MadGraphCommandConfig(
    neo_set_anubis=model,
    model_in_madgraph="UFO_HNL",
    shower="py8",
    madspin="ON",
    cache=False,
)

cards = GeneralCardInterface(config)
cards.run_card_builder.set("nevents", 2000)
cards.run_card_builder.set("ebeam1", 6800)
cards.run_card_builder.set("ebeam2", 6800)

cards.madspin_builder.clear_decays()
cards.madspin_builder.add_decay("decay n1 > ell ell vv")

job = cards.jobscript_builder
job.add_process("generate p p > n1 ell # [QCD]")
job.set_output_launch("HNL_ANUBIS_scan")
job.configure_cards()
job.add_parameter_scan("MN1", "[0.5, 1.0, 2.0]")
job.add_parameter_scan("VeN1", "[1e-6, 1e-5]")

jobscript = job.serialize()
run_card = cards.run_card_builder.serialize()
param_card = cards.param_card
madspin_card = cards.madspin_builder.serialize()
pythia_card = cards.pythia_builder.serialize()

Run layout and ingestion

The database importer understands the conventional MadGraph Events layout and scan summaries:

<campaign>/
  Events/
    run_01/
      tag_1_pythia8_events.hepmc.gz
      run_01_tag_1_banner.txt
    run_01_decayed_1/
      tag_1_pythia8_events.hepmc.gz
  scan_run_01.txt

Cards, banners, scan parameters, cross sections and event references can then be associated with a single model point. The persistent analysis object is normally a compact selection-ready dataframe bundle; retaining the raw HepMC file remains an explicit option for benchmark or archival runs.

Execution backends

Once the card strings have been prepared, the corresponding runner can be selected for the target environment:

from setanubis import MadgraphInterface, MadGraphDockerRunner

runner = MadGraphDockerRunner()
interface = MadgraphInterface(
    madgraph_runner=runner,
    jobscript_str=jobscript,
    param_card_str=param_card,
    run_card_str=run_card,
    pythia_card_str=pythia_card,
    madspin_card_str=madspin_card,
)
interface.run()
interface.retrieve_events("db/Temp/madgraph/Events")

The Docker backend isolates the generator toolchain from the Python environment. For publication-quality production, record the image digest, generator version, cards, random seeds and host information together with the campaign metadata.