Fix missing photon reconstruction caused by charged track overlap in MatchClusters.cc

[qunib]

Previously, some photons that overlapped with charged tracks were being incorrectly discarded, leading to reduced reconstruction efficiency. This change adjusts the matching logic to retain valid photons without affecting charged particle suppression.

Briefly, what does this PR introduce?

This PR improves the cluster-to-MC association logic in MatchClusters by selecting the best MC particle per cluster based on association weight, instead of taking the first match found. Default behavior is slightly changed for clusters with multiple MC associations; otherwise, results are identical. No API or function signature changes are required for users.

This code change :

1. Builds a map keyed by cluster object index, storing the best-associated MC id and its weight.
2. When matching charged tracks, it only removes a cluster if that cluster's best association is to that charged MC particle (and chooses the best cluster for that MC by highest association weight if multiple clusters claim the same MC). Remaining clusters are treated as neutrals.

What kind of change does this PR introduce?

• Bug fix (issue #__)
• New feature (issue #__)
• Documentation update
• Other: __

Please check if this PR fulfills the following:

• Tests for the changes have been added
• Documentation has been added / updated
• Changes have been communicated to collaborators

Does this PR introduce breaking changes? What changes might users need to make to their code?

Does this PR change default behavior?

[github-actions]

⚠️ Clang-Tidy found issue(s) with the introduced code (1/1)

No Clang-Tidy warnings found so I assume my comments were addressed

[github-actions]

Capybara summary for PR 2154

• rec_dis_10x100_minQ2=0_craterlake_10x100
• rec_dis_10x100_minQ2=1000_craterlake_tracking_only
• rec_dis_18x275_minQ2=0_craterlake_18x275
• rec_dis_18x275_minQ2=0_craterlake_18x275_MT
• rec_dis_18x275_minQ2=0_craterlake_18x275_ST_MT
• rec_dis_18x275_minQ2=1000_craterlake_18x275
• rec_dis_18x275_minQ2=1000_craterlake_18x275_MT
• rec_dis_18x275_minQ2=1000_craterlake_18x275_ST_MT
• rec_dis_5x41_minQ2=0_craterlake_5x41
• rec_e_1GeV_20GeV_craterlake
• rec_pi_1GeV_20GeV_craterlake

Last updated 2025-10-29T15:15-04:00 3afb2ee

[wdconinc]

I compared this branch before/after with #2163:

Before:
[] [Truthiness] [info] Processed 100 events, average truthiness: 530.444009

After:
[] [Truthiness] [info] Processed 100 events, average truthiness: 546.366942

Not sure why the truthiness goes up (bad direction), since the changes look fine to me.

It is possible (maybe likely) that a penalty of 1 for missing associations is not large enough. Just based on resolution alone, the E, px, py, pz would each contribute 1 in 67% (1 sigma) of the cases, so the effect of better reconstruction leading to better associations may actually lead to an increase in the truthiness since we are now more dominated by the energy and momentum resolution effects...