Proposal for a Secondary Vertex Type

[ruse-traveler]

As secondary vertexing work advances on both helix swimming techniques and the ACTS AMVF, it has become clear that additional types may be needed to encode information related to secondaries and resonance decays. This will be particularly critical for

1. benchmarking secondary vertexing algorithms against each other, and
2. facilitating comparisons between algorithms implemented in EICrecon vs. those ran in standalone analyses.

Describe the solution you'd like

A proposal was advanced by @starsdong in the 10.20.2025 Reco WG meeting:

edm4eic::SecondaryVertex:
  Description: "EIC secondary vertex"
  Author: "X. Dong"
  Members:
    - int32_t             type          // Type flag, to identify what type of vertex it is (e.g. primary, secondary, generated, etc.)
    - float               chi2          // Chi-squared of the vertex fit
    - int                 ndf           // NDF of the vertex fit
    - edm4hep::Vector4f   position      // position [mm] + time t0 [ns] of the vertex. Time is the 4th component in vector
    - edm4eic::Cov4f      positionError // Covariance matrix of the position+time. Time is the 4th component, similarly to 4vector
    - edm4hep::Vector3f   parentMomentum        // parent momentum
    - edm4hep::Vector3f   parentDecayLength     // parent decay length L
    - float               parentInvariantMass   // parent invariant mass
    - float               parentDecayLengthChi2 // parent L/dL
    - float               parentDca2PV          // parent dca to primary vertex
  VectorMembers:
    - edm4hep::Vector3f   daughterMomentum    // daughter track momentum
    - float               daughterMass        // daughter mass
    - float               daughterDca2PV      // daughter dca to primary vertex
    - float               daughterDca2PVChi2  // daughter dca/sigma to primary vertex
    - float               daughterPairIndices // pair track indices
    - float               daughterPairDca     // pair dca to primary vertex
    - float               daughterPairDcaChi2 // pair dca/sigma to primary vertex
  OneToOneRelations:
    - edm4eic::Vertex     primaryVertex // associated primary vertex
  OneToManyRelations:
    - edm4eic::ReconstructedParticle associatedParticles // particles associated to this vertex.

Describe alternatives you've considered

There are several paths to encoding this information, and are discussed further in the comments.

[ruse-traveler]

Feedback I provided ahead of the 10.20.2025 meeting:

• To me, looks like the big things this new type would add are:
  1. explicit parent/daughter relations
  2. parent/daughter kinematic info
  3. geometric info
• Some concerns:
  • New type would be hefty (lots of fields)
  • Additional fields duplicate info that could/is stored in existing types (see below)
  • Suggestions:
    1. Parent/daughter relations and kinematic info should be encoded in ReconstructedParticle::particles and ReconstructedParticle::{momentum, energy} fields
       • Current practice: for a resonance, calling getParticles() returns its decay products
       • See the FF lambda reco Algorithm for a good example:
       • Following this Would avoid need to explicitly identify parent/daughters relations in vertex type
    2. Can use ReconstructedPartcile::{referencePoint, startVertex} fields to store a resonance's decay vertex and production vertex respectively
       • eg. 0 = primary, 1 = secondary, etc.
    3. Should use existing edm4eic::Vertex::particle fields to identify particles attached to vertex
       • eg. calling getParticles() on a secondary vertex would return parent + daughters
       • Then could use particles' getParticles() to identify parent/daughters
    4. Encoding geometric info is tricky... Could take a couple approaches
       a. Add some short helper functions to edm4eic::utilities to calculate DCA, theta, L, etc. using provided vertices
       b. Or could define a type that stores only the geometric info for a particle relative to a vertex
  • Suggest opening issue on EDM4eic Github with proposed type to refine proposal

[ruse-traveler]

Responses to me from @starsdong on 10.20.2025:

1. The parent-daugther relation link is available there (associatedParticles member and through getAssociatedParticles() function, same as the edm4eic:Vertex container). However, unlike the neutral particle daughter reconstruction in the example in the forward Lambda reconstruction, charged particle momentum is changing in the magnetic field. It is important to keep and use the momentum at the secondary decay vertex for secondary particle reconstruction (invariant mass calculation) to achieve the best mass resolution.

2. I would not recommend overwriting the reconstructed particle momentum energy information with the information at the secondary vertex. It is equally useful to keep both: the tracking parameters near the beam line (which are in the current ReconstructedParticles) and the track parameters (position/momentum) at the decay vertex. Also practically overwriting ReconstructedParticles or replacing them with new objects introduce more layers to the final data structure.

3. Often the secondary particle reconstruction is dynamic. In practice, one often runs the reconstruction with a set of pretty loose cuts. Then in the final analysis, one will work on fine tuning on the topological cuts to find the best figure-of-merit measurement (e.g. signal significance for X-sec measurement etc.). This is also another reason that we prefer to keep both the ReconstructedParticle parameters (tracking parameters at beam line) and the tracking parameters at the decay vertex saved for down-stream analysis.

4. The secondary particle candidates per event are very few even with loose topological cuts. The added burden to the storage/memory due to the added new members are low.

5. Your comments regarding the util functions for calculating the DCA and other topological variables, these are actually defined in the Helix.* functions. They have been calculated when finding the secondary particle candidates, therefore will be convenient to directly save them out into the container rather than doing duplicate calculation (reconstruction) again later on. Also certainly it is a balance on the memory/storage vs. computing time. Since the added memory/storage burden is low, while doing the secondary calculation is often a NxM calculation, it would be beneficial to just save them out for down-stream analysis.

[ruse-traveler]

Responses from me to @starsdong on 10.23.2025:

The parent-daugther relation link is available there (associatedParticles member and through getAssociatedParticles() function, same as the edm4eic:Vertex container). ‎However, unlike the neutral particle daughter reconstruction in the example in the forward Lambda reconstruction, charged particle momentum is changing in the magnetic field. It is important to keep and use the momentum at the secondary decay vertex for secondary particle reconstruction (invariant mass calculation) to achieve the best mass resolution.

I see! The ZDC lambda reconstruction might still be instructive here: in that algorithm, the decay products used to reconstruct the lambda are boosted to the lambda's center of mass frame and saved in a new collection. Then, the boosted decay products are linked back their lab-frame counterparts via relations.

So one way we could go about it is that the helix algorithm saves the decay products with their momentum evaluated at the secondary vertex (in contrast to the default of being evaluated at the primary vertex) in their own collection. Then getParticles() for the secondary vertex would point to these particles!

I would not recommend overwriting the reconstructed particle momentum energy information with the information at the secondary vertex. It is equally useful to keep both: the tracking parameters near the beam line (which are in the current ReconstructedParticles) and the track parameters (position/momentum) at the decay vertex. Also practically overwriting ReconstructedParticles or replacing them with new objects introduce more layers to the final data structure

Then, building on the previous suggestion, it's not that we would be overwriting or replacing the original reconstructed particle collection: those will always be available and saved to the output! Instead, there would be additional branches associated with the re-evaluated particles!

While this does complicate the output tree by adding additional branches, this is something we can address by making sure we have solid documentation (via snippets, benchmarks, text on the website, etc.) explaining what the new branch is for/does.

Often the secondary particle reconstruction is dynamic. In practice, one often runs the reconstruction with a set of pretty loose cuts. Then in the final analysis, one will work on fine tuning on the topological cuts to find the best figure-of-merit measurement (e.g. signal significance for X-sec measurement etc.). This is also another reason that we prefer to keep both the ReconstructedParticle parameters (tracking parameters at beam line) and the tracking parameters at the decay vertex saved for down-stream analysis.

True! This is a good reason to keep both! The suggestion above would allow for this by adding a new collection of reconstructed particles evaluated at the secondary vertex. Then, if users want to rerun the algorithm with different parameters for tuning, they can do so either using the external code or by rerunning the reconstruction with updated parameters (I can provide a snippet of how to do that if need be).

The secondary particle candidates per event are very few even with loose topological cuts. The added burden to the storage/memory due to the added new members are low.

That's a fair point! Since they are very few candidates per event, memory usage won't be an issue.

But when I say "hefty", I also mean "conceptually hefty". The proposed structure would be one of the densest structures in our data model, having 20 total members. For reference, the next two densest would be edm4eic::Cluster (which has 17 members) and edm4eic::ReconstructedParticle (which has 16).

While this isn't a deal breaker by itself (there are cases when we need a dense structure!), the proposed structure mixes together several different levels of information: it encodes information that's not only exclusive to the vertex itself (its 4-vector, associated particles), but also information that's exclusive to the decay products and the resonance (momenta, mass, etc.) and book-keeping information (the pair indices).

Your comments regarding the util functions for calculating the DCA and other topological variables, these are actually defined in the Helix.* functions. They have been calculated when finding the secondary particle candidates, therefore will be convenient to directly save them out into the container rather than doing duplicate calculation (reconstruction) again later on. Also certainly it is a balance on the memory/storage vs. computing time.  Since the added memory/storage burden is low, while doing the secondary calculation is often a NxM calculation, it would be beneficial to just save them out for down-stream analysis.

Fair point! Part of my suggestion for the helper methods is account for the fact that doing things like calculating the DCA, decay length, etc. isn't limited to the helix swimming method: these calculations will be relevant for any secondary vertex calculation. I think it could be beneficial to have at least parallel methods in edm4eic that aren't scoped to the helix swimmer.

That being said, I definitely see the utility in saving the topological variables in some sort of container! Perhaps rather than defining a secondary vertex container, we could define 2 objects:

1. a component that defines the DCA for a particle wrt to a vertex, and
2. a "decay" container that collects the relevant relations + decay length.

Below is some pseudocode illustrating what these might look like and how they could be used!

components:

<... other components ...>

  ## TBD there's probably a better naming scheme for this...
  edm4eic::DCA:
    Members:
      - edm4hep::Vector3f distance
      - edm4eic::Cov3f covariance

datatypes:

<... other datatypes ...>

  ## Then we could add the component to reconstructed
  ## particle since a particle is always defined
  ## wrt to some vertex 
  ##
  ## TBD we would need to settle on if we define the
  ## DCA wrt to the reference point or wrt to the 
  ## start vertex
  edm4eic::ReconstructedParticle:
    Description: "EIC Reconstructed Particle"
    Author: "W. Armstrong, S. Joosten, F. Gaede"
    Members:
      - int32_t           type              // type of reconstructed particle. Check/set collection parameters ReconstructedParticleTypeNames and ReconstructedParticleTypeValues.
      - float             energy            // [GeV] energy of the reconstructed particle. Four momentum state is not kept consistent internally.
      - edm4hep::Vector3f momentum          // [GeV] particle momentum. Four momentum state is not kept consistent internally.
      - edm4hep::Vector3f referencePoint    // [mm] reference, i.e. where the particle has been measured
      - float             charge            // charge of the reconstructed particle.
      - float             mass              // [GeV] mass of the reconstructed particle, set independently from four vector. Four momentum state is not kept consistent internally.
      - float             goodnessOfPID     // overall goodness of the PID on a scale of [0;1]
      - edm4eic::Cov4f    covMatrix         // covariance matrix of the reconstructed particle 4vector (10 parameters).
      - int32_t           PDG               // PDG code for this particle
      - edm4eic::DCA      DCA               // NEW! defines DCA wrt to reference point or start vertex
      ## @TODO: Do we need timing info? Or do we rely on the start vertex time?
    OneToOneRelations:
      - edm4eic::Vertex      startVertex    // Start vertex associated to this particle
      - edm4hep::ParticleID  particleIDUsed // particle ID used for the kinematics of this particle
    OneToManyRelations:
      - edm4eic::Cluster     clusters       // Clusters used for this particle
      - edm4eic::Track       tracks         // Tracks used for this particle
      - edm4eic::ReconstructedParticle particles // Reconstructed particles that have been combined to this particle
      - edm4hep::ParticleID  particleIDs    // All associated particle IDs for this particle (not sorted by likelihood)
    ExtraCode:
      declaration: "
        bool isCompound() const {return particles_size() > 0;}\n
        "

<... other datatypes ...>

  ## And then we would add a new type collecting the
  ## decay info!
  ##
  ## NB if we associate the parent + daughters to the
  ## secondary vertex, then we would use the relations 
  ## to exact them, eg.
  ##
  ## for (auto decay : decays) {
  ##   particles = decay.getDecayVertex().getParticles();
  ##   for (auto particle : particles) {
  ##     /* ... do things .. */
  ##   }
  ## }
  edm4eic::Decay:
    Description: "A secondary decay"
    Author: "D. Kay"
    Members:
      - float decayLength      // parent decay length L 
      - float decayLengthChi2  // parent L/dL 
    OneToOneRelations:
      - edm4eic::Vertex decayVertex // would point to secondary vertex

[ruse-traveler]

Responses to me from @starsdong on 10.27.2025:

I see! The ZDC lambda reconstruction might still be instructive here: in that algorithm, the decay products used to reconstruct the lambda are boosted to the lambda's center of mass frame and saved in a new collection. Then, the boosted decay products are linked back their lab-frame counterparts via relations.

So one way we could go about it is that the helix algorithm saves the decay products with their momentum evaluated at the secondary vertex (in contrast to the default of being evaluated at the primary vertex) in their own collection. Then getParticles() for the secondary vertex would point to these particles!

Yes, currently the getAssocicatedParticles() will be returning all these particles. But as you said, the default is at the primary vertex, it would be good to save also the information at the decay vertex. There are a couple of complications in doing this way.

• one particle can be used for multiple secondary vertex reconstruction. At least in the initial try, one would like to keep all of them and leave the optimization to the downstream analysis. So the decay information including their momenta is probably preferred to stick with the pairs.
• one might think about just saving multiple tracking parameters to the reconstructed particles. But still this will need to be attached to each individual secondary vertex.

Then, building on the previous suggestion, it's not that we would be overwriting or replacing the original reconstructed particle collection: those will always be available and saved to the output! Instead, there would be additional branches associated with the re-evaluated particles!

While this does complicate the output tree by adding additional branches, this is something we can address by making sure we have solid documentation (via snippets, benchmarks, text on the website, etc.) explaining what the new branch is for/does.

As I commented above, it is OK to save this way, but all the secondary momentum information needs to be attached to any specific vertice. Most other information (like detector cluster, matching to other det) are mostly common. These will be largely duplicated. For secondary decays, the only information we are interested is the momentum parameters (and their covariance).

True! This is a good reason to keep both! The suggestion above...

... some pseudocode illustrating what these might look like and how they could be used!

I am replying to the above three together. Actually I think your proposal sounds good to me to split it into two objects if we are worried the length is too long. But I would propose to simply use

1. the current edm4eic::Vertex to save the secondary vertex information. We can debate further whether to keep the ReconstructedParticles as they are or move them to the decay vertex. But the structure is there so we can use the current format and may update the filling part later when needed.
2. the decay container sounds good to me which collects the relevant decay information and a link to the above Vertex.

[starsdong]

Thank you, Derek for putting the issue up and the discussions. For record, I discussed this proposal with the HF&Jet WG and received some comments on the variables. The XXXChi2 is not a good name, instead we could save the errors as many other observables. So the new structure is as folllows:

EDM4eic/edm4eic.yaml

Line 514 in b0c1ad6

edm4eic::SecondaryVertex:

[ruse-traveler]

Thank you, Derek for putting the issue up and the discussions. For record, I discussed this proposal with the HF&Jet WG and received some comments on the variables. The XXXChi2 is not a good name, instead we could save the errors as many other observables.

Gotcha! Thanks! I think that's a good approach! That way we're consistent with other variables, like you mentioned.

Also apologies, I haven't had much time to prepare another round of responses. But hopefully I can get to that this week...

[starsdong]

Derek,

do you think we can create a pull request on this now? I updated the branch to keep sync with the main. Thanks

[ruse-traveler]

do you think we can create a pull request on this now? I updated the branch to keep sync with the main. Thanks

I think we're beginning to converge (there are still some points to discuss, of course), so I think it's okay to continue this discussion in a PR!