Maia/theta energy

[Jullianwatts]

These commits are from @trholmes. I am submitting a PR because downstream
work depends on them.

Adds two energy correction plugins that look up a correction factor in a 2D
(theta, energy) table instead of applying one flat constant per subdetector:

• PhotonEMNonLinearity, electromagnetic
• HadronicThetaEnergyBinned, hadronic

The correction is applied inside Pandora, after clustering and before PFOs are
built, so cluster energies, PFO energies, and jets all come out consistent and
nothing has to be applied by hand downstream.

Also adds a three-argument RegisterNonLinearityEnergyCorrection overload taking
the bin edges and the table. The existing one-argument overload is unchanged,
and with no table supplied the plugins fall back to it, which is the identity.
So this is a no-op for anyone who does not configure a table.

These plugins have been in use in muon collider reconstruction and are being
upstreamed so they are available generally. key4hep/k4GaudiPandora#51 uses this
overload and cannot compile until this lands, and
MuonColliderSoft/MAIAConfig#90 sits on top of that.
This is a draft for now. This needs a rebase onto current master before it can be merged. Opening it so the dependency chain is visible.

[madbaron]

Thanks for upstreaming these!
I've confirmed the no-op claim holds: all four new XML flags default to false, and with no table registered the lookup returns the input energy unchanged.

I tested this in ghcr.io/muoncollidersoft/mucoll-sim-ubuntu24:post_3_1_test, against PandoraSDK 3.4.2.
This is ready from a mechanical standpoint.

I have just a couple of comments on the track-consistency comparison and about the lookup's global state:

1. In both merging algorithms, chi and chi0 are computed through different correction chains. chi0 uses GetCorrectedHadronicEnergy(parent), which runs the full plugin chain while chi uses the raw cluster sum with only the theta factor applied. The chi^2 - chi0^2 difference the cut is made on therefore absorbs the non-theta part of the correction chain rather than the daughter's contribution. In ConeBasedMergingAlgorithm this has a failure mode that inverts the intent of the flag (I'll comment inline).
2. The three new sites use GetCorrectedHadronicEnergy, but every other track-vs-cluster energy comparison in LCContent uses GetTrackComparisonEnergy. The SDK documents GetTrackComparisonEnergy as "the best energy estimate to use when comparing cluster energy to associated track momentum" corrected EM energy for EM showers, corrected hadronic otherwise. I think we should probably pick it up.

[madbaron]

At this point parentHadronicEnergy is the fully corrected parent energy, while mergedHadronicEnergy is the raw sum with only the theta factor applied. The subtraction mixes two different correction chains.

When the theta factor is below 1, the corrected parent can exceed the theta-corrected
raw sum. addedHadronicEnergy then clamps to 0, and on line 144 0 > 1 GeV is false, so the chi cut is skipped entirely and the merge proceeds unchecked.

I'd suggest computing both sides through the same path, and gating on the daughter's own energy as master does rather than on a difference of differently-corrected quantities.

[madbaron]

This is overwritten on line 137, and it already equals the value assigned in the initialiser on line 125. Safe to delete.

[madbaron]

Same chain asymmetry as in ConeBasedMergingAlgorithm: this is the fully corrected parent, while clusterEnergySum on line 133 is the theta-corrected raw sum. The chi^2 - chi0^2 cut is dominated by the correction-chain difference rather than by the daughter.

I think we should apply the same manual theta correction to the parent alone so both sides go through identical treatment.

[madbaron]

Suggest to use GetTrackComparisonEnergy(this->GetPandora()) here. It resolves to the corrected hadronic energy for hadronic clusters, so behaviour is unchanged for those, but it uses the corrected EM energy for the rest.

[madbaron]

This function-local static is keyed on (name, EnergyCorrectionType) only. Two Pandora instances in one process share a single table, and the second registration silently overwrites the first. There's no way for an algorithm to ask for its Pandora's table.

Worth noting this is currently the only global mutable state in LCContent.
Suggest keying on const pandora::Pandora * as well, with the algorithms passing &this->GetPandora().

[madbaron]

The loop skips entries whose type doesn't match, then unconditionally returns on the first survivor. If two HADRONIC tables are ever registered under different names, which one you get depends on std::map's ordering of the name strings.

We could the plugin name as a parameter, plumbed from each algorithm's XML block alongside the existing flag. This would also let a single job use different tables in different algorithms.

Related: pandora::HADRONIC is hard-coded at both merging call sites, so a table registered under any other correction type is silently ignored.

[madbaron]

value >= edges.back() returns -1, and GetCorrection then returns 1.0. So a cluster one MeV above the top energy edge jumps discontinuously from (say) 0.85 to 1.00. The same applies at both theta ends, but it's less damaging if a map is coded up to >pi.

I think we should clamp to the edge bin, making the last bin inclusive?

[madbaron]

eOverPEnergy doesn't depend on the loop iterator, so it can be moved above the for over associatedTrackList.

[madbaron]

I'll add a couple of tests for the new correction lookup and will take care of the deduplication of GetCorrection.

I'm happy to do more if you need help!