Add committed i3 test fixture + generator for extractor edge cases

[sevmag]

What

Adds a small, public i3 test fixture and the script that generates it, so the IceCube i3 extractors — starting with I3Calorimetry and the I3Extractor helpers it relies on — can finally be unit-tested. Motivated by #905.

• data/tests/i3/i3_fixture/i3_fixture_events.i3.zst — 8 hand-seeded events, each built to realise one extractor edge case. Committed (~13 MB) and cached, so CI reads it directly and never has to run icetray/PROPOSAL.
• tests/data/generate_i3_fixture.py — the generator that produces it (fixed RNG seed → reproducible; every frame validated at generation time).

It's a general extractor fixture, not calorimetry-specific — the current events happen to cover the I3Calorimetry edge cases, but the same file can back tests for other i3 extractors.

Why it's safe to commit (no IceCube-internal data)

• GCD: GraphNeT's own committed test GCD (data/tests/i3/oscNext_genie_level7_v02/…) — the fixture reuses it, no new GCD added.
• Propagation: PROPOSAL with open cross-section tables.
• Deterministic seed → reproducible.

The 8 events

Event	Extractor behaviour it exercises
through_going_muon	through-going track; deposited < entrance energy
stopping_track_contained	contained muon that ranges out inside the hull
starting_track	interaction vertex inside the hull, muon exits
tau_to_mu_decay	τ decays to a µ in-volume (track not erased)
nan_primary_energy	primary ν with NaN energy → check_primary_energy falls back to daughters
non_top_level_in_ice_nu	first in-ice ν is below the top of the tree → get_primaries recurses (find_in_ice_daughters)
no_descendants_reach_hull	nothing reaches the array → e_total = 0 + warning; empty MMCTrackList
corsika_muon_bundle	cosmic-ray muon bundle, extracted with is_corsika=True (empty target, full background)

Locations

• The i3 fixture lives under data/tests/i3/, next to the other committed test i3 data and reachable via the same TEST_DATA_DIR mechanism (src/graphnet/constants.py).
• The generator lives in tests/data/ (it's code, and data/ holds only data). Its paths are resolved relative to the file, so regeneration reads/writes the worktree regardless of which graphnet install is importable.

Running it

Inside the GraphNeT icetray Docker image:

python3 tests/data/generate_i3_fixture.py

The first run builds PROPOSAL's interpolation tables in a scratch dir (cached afterwards); full generation is a few minutes (dominated by the 10 PeV τ). The generator passes the full pre-commit suite (black/flake8/docformatter/pydocstyle/mypy).

Not in this PR

The unit tests themselves — those are the follow-up tracked in #905. This PR just lands the fixture + generator so the tests have data to read. The corsika_muon_bundle is an illustrative hand-seeded bundle (each muon is really propagated by PROPOSAL, but the multiplicity/spectrum are hand-chosen) — see #905 for the residual coverage gaps a fuller suite should still add.

Part of #905.

[Aske-Rosted]

I've put a few comments.

[Aske-Rosted]

I think this is the wrong way of going about it. Here you end up with particles which have slightly different directions, however the muon bundles in ice are actually pretty much collinear with some positional spread.

Something like:

    if i == 0:
        offset = np.zeros(3)          # core muon on the axis
    else:
        phi = 2.0 * np.pi * (i - 1) / (n - 1)
        r = CORSIKA_BUNDLE_RADIUS     # transverse offset, in meters
        offset = r * (np.cos(phi) * u + np.sin(phi) * v)
    mu_pos = vertex + offset
    ptype = "MuMinus" if i % 2 == 0 else "MuPlus"
    muon = _make_particle(ptype, energy, mu_pos, direction)   # shared direction
    tree.append_child(primary, muon)```

With CORSIKA_BUNDLE_RADIUS ~10m 

[Aske-Rosted]

This event, going by the description, is not a type of event that we actually have. If there are no charge recording then nothing is triggered.

[sevmag]

Good point I guess what I was going for are the events where the only charge we see in the detector comes from coincident background events. I will add a coincident background muon that reaches the detector

[Aske-Rosted]

I don't think this is expected to happen... If I remember correctly then the cases where I encountered a nan energy neutrino primary then it will have a neutrino daughter with a defined energy.

[sevmag]

ok I see

[Aske-Rosted]

wouldn't this fail for the nan-energy event you generated?

[sevmag]

it would fail, that is true. But this function is only called when.

frame.Has("TopPrimaryOutsideIce")
            and frame["TopPrimaryOutsideIce"].value

evaluates to true, which is only the case for the EdgeCase with the name "non_top_level_in_ice_nu"

[Aske-Rosted]

I think this looks good enough for an initial set of test events, applying the extractors to these will probably reveal if we have to do any further refining.