Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
94 changes: 94 additions & 0 deletions .github/scripts/run_fragments.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
#!/usr/bin/env python3
"""Run tagged shell fragments of a tutorial page exactly as written, then check outputs.

Mark each fence to run with an HTML comment on the line before it (invisible in
the rendered page):

<!-- ci-fragment: pythia8 -->
```bash
k4run pythia.py -n 500 ...
```

All fragments with the same tag run, in page order, in ONE fresh bash shell inside
an empty directory, so `cd` and variables carry over as they would for a reader.
Afterwards every `--validate FILE:EVENTS` output is checked with the local EDM4hep validator.
"""

import argparse
import json
import re
import subprocess
import sys
import tempfile
from pathlib import Path

from validate_edm4hep import validate

MARKER = re.compile(r"^\s*<!--\s*ci-fragment:\s*([\w.-]+)\s*-->\s*$")
FENCE = re.compile(r"^\s*```\s*(bash|sh|shell)?\s*$")


def extract(page, tag):
lines = page.read_text().splitlines()
fragments = []
for number, line in enumerate(lines):
match = MARKER.match(line)
if not match or match.group(1) != tag:
continue
opening = lines[number + 1] if number + 1 < len(lines) else ""
if not FENCE.match(opening) or not FENCE.match(opening).group(1):
sys.exit(f"{page}:{number + 1}: ci-fragment marker must precede a ```bash fence")
body = []
for inner in lines[number + 2 :]:
if FENCE.match(inner):
break
body.append(inner)
else:
sys.exit(f"{page}:{number + 2}: unterminated fence")
fragments.append((number + 3, "\n".join(body)))
if not fragments:
# Never pass vacuously: a renamed tag or reformatted page must fail loudly.
sys.exit(f"No fragments tagged {tag!r} in {page}")
return fragments


def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("page", type=Path)
parser.add_argument("tag")
parser.add_argument("--validate", action="append", default=[], metavar="FILE:EVENTS")
parser.add_argument("--print", action="store_true", help="Print the script and exit")
args = parser.parse_args()
page = args.page.resolve()
script = ["set -euo pipefail"]
for line, body in extract(page, args.tag):
script += [f"echo '+++ {page.name}:{line}' >&2", body]
script = "\n".join(script) + "\n"
if args.print:
print(script, end="")
return 0
with tempfile.TemporaryDirectory(prefix=f"fragments-{args.tag}-") as work:
work = Path(work)
(work / "fragments.sh").write_text(script)
status = subprocess.run(["bash", "fragments.sh"], cwd=work).returncode
if status:
print(
f"FAILED: fragment exited with status {status}; the failing fence is the "
f"last '+++ {page.name}:LINE' marker above",
file=sys.stderr,
)
return 1
failed = False
for item in args.validate:
name, events = item.rsplit(":", 1)
try:
result = validate(work / name, int(events))
except Exception as exc:
result = {"valid": False, "error": f"{type(exc).__name__}: {exc}"}
failed = True
print(f"{name}: {json.dumps(result, sort_keys=True)}", flush=True)
return 1 if failed else 0


if __name__ == "__main__":
sys.exit(main())
82 changes: 82 additions & 0 deletions .github/scripts/validate_edm4hep.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Adapted from ianna/mcp-server-key4hep at bde7af183f57d14cabc809f1d35b281cd4d5dd69.
"""Read every event with podio's backend-independent reader.

This is structural validation, not a physics-reference comparison. Importing
edm4hep loads dictionaries required by podio. Run in the selected stack.
"""

import math
from pathlib import Path


def validate(path, expected):
import edm4hep # noqa: F401
import ROOT
from podio.reading import get_reader

if expected <= 0 or not Path(path).is_file() or Path(path).stat().st_size == 0:
raise ValueError("Expected a nonempty output and a positive event count")
reader = get_reader(str(path))
if "events" not in reader.categories:
raise ValueError("No events category")
frames = reader.get("events")
if len(frames) != expected:
raise ValueError(f"Event count mismatch: {len(frames)} != {expected}")
particles_total = 0
schema = None
for frame in frames:
names = set(frame.getAvailableCollections())
if "MCParticles" not in names:
raise ValueError("Missing MCParticles collection")
if schema is None:
schema = sorted(names)
elif sorted(names) != schema:
raise ValueError("Collection names change between events")
# Force deserialization of every collection, not just the tree header.
for name in names:
collection = frame.get(name)
for _ in collection:
pass
particles = frame.get("MCParticles")
# podio returns std::string_view from getTypeName(). Depending on the
# cppyy/ROOT version, str(view) may describe the proxy instead of its
# contents. Check the dictionary-backed C++ class, not its string proxy.
if not isinstance(particles, ROOT.edm4hep.MCParticleCollection):
actual = getattr(type(particles), "__cpp_name__", type(particles).__name__)
raise ValueError(
"MCParticles has the wrong EDM4hep collection type: "
f"expected edm4hep::MCParticleCollection, got {actual}"
)
identifiers = set()
for particle in particles:
oid = particle.getObjectID()
identifiers.add((oid.collectionID, oid.index))
momentum = particle.getMomentum()
if not all(
math.isfinite(v)
for v in (
momentum.x,
momentum.y,
momentum.z,
particle.getMass(),
particle.getCharge(),
)
):
raise ValueError("Non-finite MCParticle values")
for particle in particles:
for related in [*particle.getParents(), *particle.getDaughters()]:
if not related.isAvailable():
raise ValueError("Unresolved MCParticle relation")
oid = related.getObjectID()
if (oid.collectionID, oid.index) not in identifiers:
raise ValueError("MCParticle relation leaves the required collection")
particles_total += len(particles)
if particles_total == 0:
raise ValueError("No MCParticles in generated sample")
return {
"valid": True,
"entries": expected,
"particles": particles_total,
"collections": schema,
"scope": "EDM4hep structure and MCParticle relations",
}
6 changes: 3 additions & 3 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ jobs:
-d ghcr.io/key4hep/key4hep-images/alma9:latest /bin/bash
- name: Run tests
run: |
docker exec CI_container /bin/bash -c \
'curl -LO https://github.com/jgm/pandoc/releases/download/3.10/pandoc-3.10-linux-amd64.tar.gz;\
docker exec CI_container /bin/bash -e -c \
'curl -fLO https://github.com/jgm/pandoc/releases/download/3.10/pandoc-3.10-linux-amd64.tar.gz;\
tar -xzf pandoc-3.10-linux-amd64.tar.gz;\
cp pandoc-3.10/bin/pandoc /usr/local/bin/;\
cd ./Package;\
Expand All @@ -38,5 +38,5 @@ jobs:
cd build;\
cmake ..;\
make;\
make test;
ctest --output-on-failure --no-tests=error;
'
7 changes: 5 additions & 2 deletions 2-gen-and-fastsim/2-1-event-generation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,23 +93,26 @@ The Gaudi steering file needs to activate the `GaudiTool` that interfaces
An example of steering file can be found at [pythia.py][pythia-example].
The steering file runs the minimal set of algorithms to run Pythia8 and produce
an output in `EDM4hep` format:
<!-- ci-fragment: pythia8 -->
```bash
wget https://raw.githubusercontent.com/HEP-FCC/k4Gen/main/k4Gen/options/pythia.py
k4run --dry-run pythia.py
```
with expected output
```
[k4run - INFO] k4run.main: --> Pythia8 --> HepMCToEDMConverter --> StableParticles --> out
[k4run - INFO] k4run.main: --> eventHeaderCreator --> Pythia8 --> HepMCToEDMConverter --> StableParticles
[...]
```
For example, to generate 500 $e^{+}e^{-} \rightarrow \mu^{+}\mu^{-}$ at
91.2 GeV, one can do the following, download the configuration file:
<!-- ci-fragment: pythia8 -->
```bash
wget https://raw.githubusercontent.com/HEP-FCC/FCC-config/main/FCCee/Generator/Pythia8/p8_ee_Zmumu_ecm91.cmd
```
and run
<!-- ci-fragment: pythia8 -->
```bash
k4run pythia.py -n 500 --out.filename p8_mumu_500.e4h.root --Pythia8.PythiaInterface.pythiacard p8_ee_Zmumu_ecm91.cmd
k4run pythia.py -n 500 --IOSvc.Output p8_mumu_500.e4h.root --Pythia8.PythiaInterface.pythiacard p8_ee_Zmumu_ecm91.cmd
```


Expand Down
13 changes: 13 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,16 @@ add_nb_test("2-gen-and-fastsim/2-1-event-generation/README")
add_nb_test("2-gen-and-fastsim/2-2-fastsim-delphes/README")
add_nb_test("3-analysis/3-1-higgs-analysis/README")
add_nb_test("4-full-detector-sim/FccCaloPerformance/CaloFullSimExercise")

# Shell fragments run verbatim (see .github/scripts/run_fragments.py), followed by
# structural EDM4hep validation of the files the tutorial tells readers to produce.
function(add_fragment_test page tag)
get_filename_component(_page_dir ${CMAKE_SOURCE_DIR}/${page} DIRECTORY)
add_test(NAME ${page}-fragments-${tag}
COMMAND python3 ${CMAKE_SOURCE_DIR}/.github/scripts/run_fragments.py
${CMAKE_SOURCE_DIR}/${page}.md ${tag} ${ARGN}
WORKING_DIRECTORY ${_page_dir})
endfunction()

add_fragment_test("2-gen-and-fastsim/2-1-event-generation/README" pythia8
--validate p8_mumu_500.e4h.root:500)
Loading