# ksl111/madgraph5_signal_simulation architecture

> Architecture diagram of the GitHub repository ksl111/madgraph5_signal_simulation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ksl111/madgraph5_signal_simulation
- Repository: https://github.com/ksl111/madgraph5_signal_simulation

## Overview

This repository manages RunIII2024Summer24 signal-MC production for a 2HDM+a mono-Z campaign, from mass-point cards through NanoAOD on EOS. The documented workflow generates MadGraph gridpacks, prepares CMSSW configs, schedules independent point/seed jobs, validates outputs, and merges completed NanoAOD chunks. Separate analysis capabilities produce kinematic and trigger plots and inspect MadEvent integration channels and model diagrams. The graph follows README-documented orchestration; some scripts and analysis inputs were not sampled, so uncertain implementation-level links are omitted.

Main entry points: [`scripts/03_chain.sh`](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/03_chain.sh) (Event chain), [`scripts/01_gridpack.sh`](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/01_gridpack.sh) (Gridpack builder), [`scripts/05_plots.py`](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/05_plots.py) (Kinematics plots), [`scripts/00_cards.sh`](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/00_cards.sh) (Point cards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Campaign setup"]
  node_config["Campaign config<br/>[config.sh]"]
  node_cards["Point cards<br/>[00_cards.sh]"]
  node_card_templates["Card templates"]
end

subgraph group_production["Event production"]
  node_gridpack["Gridpack builder<br/>[01_gridpack.sh]"]
  node_cms_configs["CMSSW configs<br/>[02_cfg.sh]"]
  node_fragment["LHE and Pythia<br/>[fragment.py]"]
  node_chain["Event chain<br/>[03_chain.sh]"]
  node_merge["NanoAOD merge<br/>[04_merge.sh]"]
end

subgraph group_operations["Production operations"]
  node_joblist["Seed job list<br/>[make_joblist.sh]"]
  node_preflight["Preflight checks<br/>[preflight.sh]"]
  node_status["Run monitoring<br/>[status.sh]"]
end

subgraph group_validation["Validation"]
  node_gridpack_check["Gridpack checks<br/>[check_gridpack.sh]"]
  node_nano_check["NanoAOD checks<br/>[check_nano.py]"]
  node_physics_check["Physics checks<br/>[check_physics.py]"]
end

subgraph group_analysis["Analysis"]
  node_plot_wrapper["Plot runner<br/>[05_plots.sh]"]
  node_plots["Kinematics plots<br/>[05_plots.py]"]
  node_plot_pdf["Plot PDF"]
  node_channel_analysis["Channel analysis<br/>[06_channels.py]"]
  node_model_analysis["Model diagrams<br/>[06_model.py]"]
  node_model_runner["Model runner<br/>[06_model.sh]"]
  node_model_outputs["Diagram outputs"]
  node_idm_lhe_plots["IDM MET plots<br/>[plot_met.py]"]
end

node_researcher(("Campaign operator"))
node_madgraph["MadGraph"]
node_gridpack_store[("EOS gridpacks")]
node_cmsrun["CMSSW processing"]
node_condor["HTCondor jobs<br/>[submit.sub]"]
node_eos_nano[("EOS NanoAOD")]
node_channel_logs["MadEvent logs"]
node_idm_lhe["IDM LHE files"]

node_researcher -->|"generates cards"| node_cards
node_config -->|"sets grid"| node_cards
node_cards -->|"renders"| node_card_templates
node_researcher -->|"requests gridpack"| node_gridpack
node_gridpack -->|"builds with"| node_madgraph
node_gridpack -->|"stores"| node_gridpack_store
node_researcher -->|"checks gridpack"| node_gridpack_check
node_gridpack_check -->|"checks contents"| node_gridpack_store
node_researcher -->|"prepares configs"| node_cms_configs
node_cms_configs -->|"configures steps"| node_cmsrun
node_researcher -->|"runs point"| node_chain
node_chain -->|"uses generator"| node_fragment
node_chain -->|"runs stages"| node_cmsrun
node_chain -->|"uses gridpack"| node_gridpack_store
node_researcher -->|"builds queue"| node_joblist
node_joblist -->|"skips completed"| node_eos_nano
node_researcher -->|"checks readiness"| node_preflight
node_preflight -->|"gates submission"| node_condor
node_researcher -->|"submits jobs"| node_condor
node_condor -->|"runs jobs"| node_chain
node_chain -->|"writes NanoAOD"| node_eos_nano
node_researcher -->|"monitors run"| node_status
node_researcher -->|"merges chunks"| node_merge
node_merge -->|"reads chunks"| node_eos_nano
node_researcher -->|"checks files"| node_nano_check
node_researcher -->|"checks signal"| node_physics_check
node_researcher -->|"makes plots"| node_plot_wrapper
node_plot_wrapper -->|"runs"| node_plots
node_plots -->|"reads NanoAOD"| node_eos_nano
node_plots -->|"writes PDF"| node_plot_pdf
node_researcher -->|"analyzes channels"| node_channel_analysis
node_channel_analysis -->|"reads logs"| node_channel_logs
node_researcher -->|"inspects model"| node_model_runner
node_model_runner -->|"runs analysis"| node_model_analysis
node_model_analysis -->|"writes diagrams"| node_model_outputs
node_researcher -->|"plots IDM MET"| node_idm_lhe_plots
node_idm_lhe_plots -->|"reads LHE"| node_idm_lhe

click node_config "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/config.sh"
click node_cards "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/00_cards.sh"
click node_card_templates "https://github.com/ksl111/madgraph5_signal_simulation/tree/main/cards/tmpl"
click node_gridpack "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/01_gridpack.sh"
click node_gridpack_check "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/check_gridpack.sh"
click node_cms_configs "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/02_cfg.sh"
click node_fragment "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/fragments/fragment.py"
click node_chain "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/03_chain.sh"
click node_joblist "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/make_joblist.sh"
click node_preflight "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/preflight.sh"
click node_condor "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/condor/submit.sub"
click node_status "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/status.sh"
click node_merge "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/04_merge.sh"
click node_nano_check "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/check_nano.py"
click node_physics_check "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/check_physics.py"
click node_plot_wrapper "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/05_plots.sh"
click node_plots "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/05_plots.py"
click node_channel_analysis "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/06_channels.py"
click node_model_analysis "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/06_model.py"
click node_model_runner "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/06_model.sh"
click node_model_outputs "https://github.com/ksl111/madgraph5_signal_simulation/tree/main/docs/data"
click node_idm_lhe_plots "https://github.com/ksl111/madgraph5_signal_simulation/blob/main/test_idm/analysis/plot_met.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_cards,node_card_templates toneBlue
class node_gridpack,node_cms_configs,node_fragment,node_chain,node_merge,node_gridpack_store,node_eos_nano toneAmber
class node_joblist,node_preflight,node_status toneMint
class node_gridpack_check,node_nano_check,node_physics_check toneRose
class node_plot_wrapper,node_plots,node_plot_pdf,node_channel_analysis,node_model_analysis,node_model_runner,node_model_outputs,node_idm_lhe_plots,node_researcher,node_madgraph,node_cmsrun,node_channel_logs,node_idm_lhe toneIndigo
class node_condor toneTeal
```

## Components

### Campaign setup

- [Campaign config](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/config.sh): `config.sh`
- [Point cards](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/00_cards.sh): `scripts/00_cards.sh`
- [Card templates](https://github.com/ksl111/madgraph5_signal_simulation/tree/main/cards/tmpl): `cards/tmpl`

### Event production

- [Gridpack builder](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/01_gridpack.sh): `scripts/01_gridpack.sh`
- [CMSSW configs](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/02_cfg.sh): `scripts/02_cfg.sh`
- [LHE and Pythia](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/fragments/fragment.py): `fragments/fragment.py`
- [Event chain](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/03_chain.sh): `scripts/03_chain.sh`
- [NanoAOD merge](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/04_merge.sh): `scripts/04_merge.sh`

### Production operations

- [Seed job list](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/make_joblist.sh): `scripts/make_joblist.sh`
- [Preflight checks](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/preflight.sh): `scripts/preflight.sh`
- [Run monitoring](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/status.sh): `scripts/status.sh`

### Validation

- [Gridpack checks](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/check_gridpack.sh): `scripts/check_gridpack.sh`
- [NanoAOD checks](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/check_nano.py): `scripts/check_nano.py`
- [Physics checks](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/check_physics.py): `scripts/check_physics.py`

### Analysis

- [Plot runner](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/05_plots.sh): `scripts/05_plots.sh`
- [Kinematics plots](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/05_plots.py): `scripts/05_plots.py`
- **Plot PDF**
- [Channel analysis](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/06_channels.py): `scripts/06_channels.py`
- [Model diagrams](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/06_model.py): `scripts/06_model.py`
- [Model runner](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/scripts/06_model.sh): `scripts/06_model.sh`
- [Diagram outputs](https://github.com/ksl111/madgraph5_signal_simulation/tree/main/docs/data): `docs/data`
- [IDM MET plots](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/test_idm/analysis/plot_met.py): `test_idm/analysis/plot_met.py`

### Other components

- **Campaign operator**
- **MadGraph**
- **EOS gridpacks**
- **CMSSW processing**
- [HTCondor jobs](https://github.com/ksl111/madgraph5_signal_simulation/blob/main/condor/submit.sub): `condor/submit.sub`
- **EOS NanoAOD**
- **MadEvent logs**
- **IDM LHE files**

## Connections

- Campaign operator → Point cards: generates cards (evidence: `README.md`)
- Campaign config → Point cards: sets grid (evidence: `README.md`)
- Point cards → Card templates: renders (evidence: `README.md`)
- Campaign operator → Gridpack builder: requests gridpack (evidence: `README.md`)
- Gridpack builder → MadGraph: builds with (evidence: `README.md`)
- Gridpack builder → EOS gridpacks: stores (evidence: `README.md`)
- Campaign operator → Gridpack checks: checks gridpack (evidence: `README.md`)
- Gridpack checks → EOS gridpacks: checks contents (evidence: `README.md`)
- Campaign operator → CMSSW configs: prepares configs (evidence: `README.md`)
- CMSSW configs → CMSSW processing: configures steps (evidence: `README.md`)
- Campaign operator → Event chain: runs point (evidence: `README.md`)
- Event chain → LHE and Pythia: uses generator (evidence: `README.md`)
- Event chain → CMSSW processing: runs stages (evidence: `README.md`)
- Event chain → EOS gridpacks: uses gridpack (evidence: `README.md`)
- Campaign operator → Seed job list: builds queue (evidence: `README.md`)
- Seed job list → EOS NanoAOD: skips completed (evidence: `README.md`)
- Campaign operator → Preflight checks: checks readiness (evidence: `README.md`)
- Preflight checks → HTCondor jobs: gates submission (evidence: `README.md`)
- Campaign operator → HTCondor jobs: submits jobs (evidence: `README.md`)
- HTCondor jobs → Event chain: runs jobs (evidence: `README.md`)
- Event chain → EOS NanoAOD: writes NanoAOD (evidence: `README.md`)
- Campaign operator → Run monitoring: monitors run (evidence: `README.md`)
- Campaign operator → NanoAOD merge: merges chunks (evidence: `README.md`)
- NanoAOD merge → EOS NanoAOD: reads chunks (evidence: `README.md`)
- Campaign operator → NanoAOD checks: checks files (evidence: `README.md`)
- Campaign operator → Physics checks: checks signal (evidence: `README.md`)
- Campaign operator → Plot runner: makes plots (evidence: `README.md`)
- Plot runner → Kinematics plots: runs (evidence: `README.md`)
- Kinematics plots → EOS NanoAOD: reads NanoAOD (evidence: `README.md`)
- Kinematics plots → Plot PDF: writes PDF (evidence: `README.md`)
- Campaign operator → Channel analysis: analyzes channels (evidence: `README.md`)
- Channel analysis → MadEvent logs: reads logs (evidence: `README.md`)
- Campaign operator → Model runner: inspects model
- Model runner → Model diagrams: runs analysis (evidence: `scripts/06_model.py`)
- Model diagrams → Diagram outputs: writes diagrams (evidence: `scripts/06_model.py`)
- Campaign operator → IDM MET plots: plots IDM MET (evidence: `test_idm/analysis/plot_met.py`)
- IDM MET plots → IDM LHE files: reads LHE (evidence: `test_idm/analysis/plot_met.py`)
