Skip to content

Gen/ee: the fixes after #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kjvbrt wants to merge 3 commits into
base: main
Choose a base branch
from
+122 −81
Open

Gen/ee: the fixes after #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c3a90c2
Gen/ee: clone/cd instructions, OMP_NUM_THREADS, blockquote Q&A, renam…
kjvbrt Sep 1, 2026
5652472
Clarify "background" terminology, drop unmade-slides/presenting claims
kjvbrt Sep 1, 2026
791da47
Fix cd path in Gen/ee/README.md's getting-started snippet
kjvbrt Sep 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 99 additions & 76 deletions Gen/ee/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,13 @@ generator WHIZARD generates the hard process
$e^{+}e^{-} \rightarrow \mu^{+} \mu^{-} H$, then Pythia8 showers,
hadronizes, and decays $H \rightarrow b \bar{b}$.

All commands below assume you start from the `Gen/ee` folder in the cloned
repository:

```bash
cd Gen/ee

@davidlange6 davidlange6 Sep 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

consider stating with a git clone and cd into the cloned repo?

```


## Environment setup

Expand Down Expand Up @@ -108,21 +115,27 @@ Run it in its own directory, as WHIZARD produces a lot of additional helper
files:

```bash
mkdir -p test_whizard/mumuH && cd test_whizard/mumuH
mkdir -p whizard_prod/mumuH && cd whizard_prod/mumuH
cp ../../mumuH.sin .
whizard mumuH.sin
OMP_NUM_THREADS=1 whizard mumuH.sin
```

This produces `mumuH.lhe`.

> **Note:** WHIZARD also computes and prints the process cross-section
> during the `integrate` step above — look for the `Integral[fb]`/
> `Error[fb]` columns in the last combined row of the iteration table
> (also echoed in the generated `mumuH.log` file). This is the
> cross-section for the exact final state computed here
> ($e^{+}e^{-} \rightarrow \mu^{+} \mu^{-} H$), not the total $ZH$
> production cross-section — it already includes the
> $Z \rightarrow \mu^{+} \mu^{-}$ branching fraction (~3.37%).
> Notes:
> 1. WHIZARD uses OpenMP and by default grabs all available cores on the
> machine, which isn't friendly (or efficient) on shared/multi-user
> nodes. `OMP_NUM_THREADS=1` restricts it to a single thread; drop it
> if you're on a machine you have exclusively to yourself and want the
> integration step to finish faster.

@davidlange6 davidlange6 Sep 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think i would not suggest unsetting OMP_NUM_THREADS unless one knows what they are doing. Only for heavyweight processes will increasing the number of threads help.

> 2. WHIZARD also computes and prints the process cross-section during
> the `integrate` step above — look for the `Integral[fb]`/`Error[fb]`
> columns in the last combined row of the iteration table (also echoed
> in the generated `mumuH.log` file). This is the cross-section for
> the exact final state computed here
> ($e^{+}e^{-} \rightarrow \mu^{+} \mu^{-} H$), not the total $ZH$
> production cross-section — it already includes the
> $Z \rightarrow \mu^{+} \mu^{-}$ branching fraction (~3.37%).

Two settings are deliberately left out rather than pinned explicitly,
relying on their WHIZARD defaults:
Expand All @@ -135,31 +148,31 @@ relying on their WHIZARD defaults:
> file into Pythia8 downstream, see
> [WHIZARD manual](https://whizard.hepforge.org/manual.pdf).

<details open>
<summary><strong>❓ Question:</strong></summary>

WHIZARD generates $e^{+}e^{-} \rightarrow \mu^{+} \mu^{-} H$ directly. Why
not $e^{+}e^{-} \rightarrow Z H$ with $Z \rightarrow \mu^{+} \mu^{-}$
instead — isn't the final state identical?

<details>
<summary><strong>✅ Answer:</strong></summary>

WHIZARD computes the complete matrix element for the exact final state
directly, rather than treating it as production ($e^{+}e^{-} \rightarrow Z
H$) followed by a separate, on-shell $Z \rightarrow \mu^{+} \mu^{-}$
decay. WHIZARD does support that factorized "cascade decay" mode too, and
it can retain full spin correlations between production and decay, but it
still restricts the intermediate boson to being on-shell, discarding the
true Breit-Wigner off-shell tails and any other diagrams contributing to
the same final state that don't proceed through that resonance ([WHIZARD
reference paper](https://arxiv.org/abs/0708.4233), Section 6.6). At
$\sqrt{s} = 240$ GeV there's only about 24 GeV of phase space left over the
$H + Z$ mass threshold, so the $Z$'s few-GeV width has a non-negligible
effect on the exact lineshape.

</details>
</details>
> <details open>
> <summary><strong>❓ Question:</strong></summary>
>
> WHIZARD generates $e^{+}e^{-} \rightarrow \mu^{+} \mu^{-} H$ directly. Why
> not $e^{+}e^{-} \rightarrow Z H$ with $Z \rightarrow \mu^{+} \mu^{-}$
> instead — isn't the final state identical?
>
> <details>
> <summary><strong>✅ Answer:</strong></summary>
>
> WHIZARD computes the complete matrix element for the exact final state
> directly, rather than treating it as production ($e^{+}e^{-} \rightarrow Z
> H$) followed by a separate, on-shell $Z \rightarrow \mu^{+} \mu^{-}$
> decay. WHIZARD does support that factorized "cascade decay" mode too, and
> it can retain full spin correlations between production and decay, but it
> still restricts the intermediate boson to being on-shell, discarding the
> true Breit-Wigner off-shell tails and any other diagrams contributing to
> the same final state that don't proceed through that resonance ([WHIZARD
> reference paper](https://arxiv.org/abs/0708.4233), Section 6.6). At
> $\sqrt{s} = 240$ GeV there's only about 24 GeV of phase space left over the
> $H + Z$ mass threshold, so the $Z$'s few-GeV width has a non-negligible
> effect on the exact lineshape.
>
> </details>
> </details>


## Step 2: Pythia8 - shower, hadronize, decay $H \rightarrow b \bar{b}$
Expand All @@ -175,13 +188,13 @@ script"; `k4run` is Key4hep's command-line tool for running these scripts.
> 1. To get a list of all available commandline arguments which one can use to

@davidlange6 davidlange6 Sep 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fwiw, the information flow in this section does not seem to follow a logical order as it starts with steering files, goes back to pythia files and eventually comes back to an actual steering file

(but thats not an issue with this PR).

> adjust the steering script use:
> ```bash
> k4run steering_script.py --help
> k4run <steering_script.py> --help
> ```
> 2. To check that a steering script is valid without actually running the
> job (parses the config, wires up components, but generates no events),
> use:
> ```bash
> k4run steering_script.py --dry-run
> k4run <steering_script.py> --dry-run
> ```
> 3. Gaudi components of the Key4hep ecosystem are spread through many
> packages, here we primarily use the Gaudi components from
Expand Down Expand Up @@ -214,26 +227,26 @@ LesHouches:matchInOut = off
25:onIfAny = 5
```

<details open>
<summary><strong>❓ Question:</strong></summary>

The card sets `PartonLevel:ISR = off` but leaves `PartonLevel:FSR` on
(Pythia8's default). Shouldn't initial- and final-state radiation be
treated the same way?

<details>
<summary><strong>✅ Answer:</strong></summary>

WHIZARD's `isr_handler`, turned on in Step 1, already applied the
initial-state radiation, as an energy redistribution on the beam momenta, so
Pythia8's own initial-state shower would double-count it if left on. FSR is
different: the LHE file from Step 1 has the Higgs *undecayed*, and Pythia8's
final-state shower is what both decays $H \rightarrow b \bar{b}$ and showers the
resulting $b/\bar{b}$ before hadronization. Turn it off and the $b/\bar{b}$ go
straight into string fragmentation with zero shower.

</details>
</details>
> <details open>
> <summary><strong>❓ Question:</strong></summary>
>
> The card sets `PartonLevel:ISR = off` but leaves `PartonLevel:FSR` on
> (Pythia8's default). Shouldn't initial- and final-state radiation be
> treated the same way?
>
> <details>
> <summary><strong>✅ Answer:</strong></summary>
>
> WHIZARD's `isr_handler`, turned on in Step 1, already applied the
> initial-state radiation, as an energy redistribution on the beam momenta, so
> Pythia8's own initial-state shower would double-count it if left on. FSR is
> different: the LHE file from Step 1 has the Higgs *undecayed*, and Pythia8's
> final-state shower is what both decays $H \rightarrow b \bar{b}$ and showers the
> resulting $b/\bar{b}$ before hadronization. Turn it off and the $b/\bar{b}$ go
> straight into string fragmentation with zero shower.
>
> </details>
> </details>

The steering script [`pythia_gen.py`](pythia_gen.py) reads the card above. No
HepMC file is ever written to disk here: `GenAlg` writes the
Expand Down Expand Up @@ -322,33 +335,36 @@ iosvc = IOSvc()
iosvc.Output = "mumuH_Hbb.root"
```

<details open>
<summary><strong>❓ Question:</strong></summary>

The script sets `pythia8gen.ErrorMax = 20`. What do you think would happen
at this stage's actual sample size (10,000 events) if this were left at
Gaudi's default, `ErrorMax = 1`?

<details>
<summary><strong>✅ Answer:</strong></summary>

A small fraction of events (roughly 1 in a few thousand) hit a Pythia8-level
failure that retrying doesn't recover from — for example an energy-momentum
conservation check. With `ErrorMax = 1`, a single such event aborts the *entire*
run, not just that one event. Raising `ErrorMax` lets Gaudi skip a handful of
individually-unrecoverable events and keep going instead.

</details>
</details>
> <details open>
> <summary><strong>❓ Question:</strong></summary>
>
> The script sets `pythia8gen.ErrorMax = 20`. What do you think would happen
> at this stage's actual sample size (10,000 events) if this were left at
> Gaudi's default, `ErrorMax = 1`?
>
> <details>
> <summary><strong>✅ Answer:</strong></summary>
>
> A small fraction of events (roughly 1 in a few thousand) hit a Pythia8-level
> failure that retrying doesn't recover from — for example an energy-momentum
> conservation check. With `ErrorMax = 1`, a single such event aborts the *entire*
> run, not just that one event. Raising `ErrorMax` lets Gaudi skip a handful of
> individually-unrecoverable events and keep going instead.
>
> </details>
> </details>

> **Note:** Gaudi itself flags `ErrorMax` as `[[deprecated]]` (a warning
> appears at run time), but as of this Key4hep release there's no
> replacement — the property is still fully functional under the hood, so
> this tutorial keeps using it as-is until a better alternative exists.

Copy both files next to the LHEf file produced in Step 1 and run:
Set up a separate directory for this step, copy in the LHEf file produced
in Step 1 alongside the card and steering script, and run:

```bash
cd ../.. && mkdir -p pythia_prod/mumuH && cd pythia_prod/mumuH
cp ../../whizard_prod/mumuH/mumuH.lhe .
cp ../../mumuH_Hbb.cmd ../../pythia_gen.py .
k4run pythia_gen.py
```
Expand All @@ -373,6 +389,13 @@ Pythia8 generates these hard processes itself. See
[`solutions/backgrounds.md`](solutions/backgrounds.md) for the walkthrough; the
cards themselves are also in the [`solutions/`](solutions) folder.

> **Note:** "Background" here means a different *physics process* (WW,
> ZZ) that can mimic the mumuH signal in the final state — not the
> beam-induced background familiar from FullSim studies, where machine-
> related backgrounds are overlaid onto a signal event at the
> simulation/reconstruction level. This tutorial's fast simulation chain
> doesn't include beam-induced background overlay at all.


## What's next

Expand Down
11 changes: 9 additions & 2 deletions Gen/ee/solutions/backgrounds.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,13 @@ e+e- -> WW and e+e- -> ZZ (diboson) production. Unlike the signal, these
don't need WHIZARD: Pythia8 can generate the hard process itself directly,
so this is a single Pythia8 step with no LHE file involved at all.

> **Note:** "Background" here means a different *physics process* (WW,

@davidlange6 davidlange6 Sep 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this text is also in the readme. Is that sufficient?

> ZZ) that can mimic the mumuH signal in the final state — not the
> beam-induced background familiar from FullSim studies, where machine-
> related backgrounds are overlaid onto a signal event at the
> simulation/reconstruction level. This tutorial's fast simulation chain
> doesn't include beam-induced background overlay at all.

Both reuse the signal's [`pythia_gen.py`](../pythia_gen.py) steering script
as-is — only the card and output filename change, and both are overridable
at the command line via `k4run`'s property overrides, so no file edits or
Expand All @@ -20,7 +27,7 @@ IDEA values used for the signal instead — so smearing is consistent across
signal and backgrounds, rather than each card using its own values.

```bash
mkdir -p test_whizard/WW && cd test_whizard/WW
mkdir -p pythia_prod/WW && cd pythia_prod/WW
cp ../../solutions/p8_ee_WW_ecm240.cmd ../../pythia_gen.py .
k4run pythia_gen.py --Pythia8.PythiaInterface.pythiacard=p8_ee_WW_ecm240.cmd --IOSvc.Output=WW.root
```
Expand All @@ -36,7 +43,7 @@ electroweak diboson process — dominated by ZZ away from resonance, but
also including some gamma*/Z interference, hence the setting name):

```bash
mkdir -p test_whizard/ZZ && cd test_whizard/ZZ
mkdir -p pythia_prod/ZZ && cd pythia_prod/ZZ
cp ../../solutions/p8_ee_ZZ_ecm240.cmd ../../pythia_gen.py .
k4run pythia_gen.py --Pythia8.PythiaInterface.pythiacard=p8_ee_ZZ_ecm240.cmd --IOSvc.Output=ZZ.root
```
Expand Down
17 changes: 14 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,18 @@ Fast/Parametric **S**imulation (Delphes) to physics **Ana**lysis.
- **FCC-hh (shorter, advanced transfer):** HH -> b b gamma gamma, reusing the FCC-ee
material with less hand-holding, extending the physics objects covered to photons.

## Getting started

Clone the repository:

```bash
git clone https://github.com/HEP-FCC/GenToAna-Tutorial.git
cd GenToAna-Tutorial
```

(If you plan to submit fixes, fork the repo first and clone your fork
instead — see [CONTRIBUTING.md](CONTRIBUTING.md).)

## Structure

Each stage has its own top-level directory, split by collider, with a
Expand All @@ -35,9 +47,8 @@ Analysis/

## Format

Each section is introduced with brief slides, then students work through the
markdown material directly in this repo (VSCodium + extensions recommended
for an all-in-one setup). Students present their solutions; reference
Students work through the markdown material directly in this repo
(VSCodium + extensions recommended for an all-in-one setup). Reference
solutions are also provided here for offline use.

## Branches
Expand Down