Description

skuditha

opened on Apr 21, 2026

Issue body actions

There appears to be a mismatch between the documented meaning of several fields in the REC::VertDoca bank and what is actually written in the reconstruction code.

According to the bank definition in:
coatjava/etc/bankdefs/hipo4/even.json

the fields are described as direction vectors:

{"name":"cx1", "info":"x-direction vector of the first track at the DOCA point (cm)"},
{"name":"cy1", "info":"y-direction vector of the first track at the DOCA point (cm)"},
{"name":"cz1", "info":"z-direction vector of the first track at the DOCA point (cm)"},
...
{"name":"cx2", "info":"x-direction vector of the second track at the DOCA point (cm)"},
{"name":"cy2", "info":"y-direction vector of the second track at the DOCA point (cm)"},
{"name":"cz2", "info":"z-direction vector of the second track at the DOCA point (cm)"},

However, in the actual implementation (coatjava/reconstruction/vtx/src/main/java/org/jlab/rec/vtx/banks/Writer.java):

bank.setFloat("cx1", i, (float) vtx.get(i).getP1().getPx());
bank.setFloat("cy1", i, (float) vtx.get(i).getP1().getPy());
bank.setFloat("cz1", i, (float) vtx.get(i).getP1().getPz());

bank.setFloat("cx2", i, (float) vtx.get(i).getP2().getPx());
bank.setFloat("cy2", i, (float) vtx.get(i).getP2().getPy());
bank.setFloat("cz2", i, (float) vtx.get(i).getP2().getPz());

These area clearly momentum components (px, py, pz), not direction vectors.

Expected Behaviour

Either:

1. The documentation should reflect that these fields store momentum components (px, py, pz), or
2. The implementation should be updated to store normalized direction vectors if that was the original intent.

Impact

This discrepancy can lead to:

• Misinterpretation of the variables in analysis code
• Incorrect physics usage (e.g., assuming unit vectors when magnitudes are present)
• Potential downstream bugs in reconstruction or ML workflows

Activity

1. baltzell

   linked a pull request that will close this issuefix: indexing issue between DECAYS::Particle and REC::VertDoca bank #1212on Apr 29, 2026
2. baltzell

   closed this as completedon Apr 29, 2026
3. c-dilks commented on Apr 30, 2026

   

   c-dilks

   on Apr 30, 2026

   Member

   More actions

   Is this actually solved? I thought this was more of a documentation issue.
4. c-dilks

   reopened this on Apr 30, 2026
5. skuditha commented on Apr 30, 2026

   

   skuditha

   on Apr 30, 2026

   ContributorAuthor

   More actions

   No Chris! It is not solved. Thanks for catching it.

   The pull request linked (#1212) is for a separate problem. I didn't create an "issue" for it as it was a trivial fix.

   This "issue" (1217) has two potential solutions:

   1. fix the documentation (and variable names)
   2. fix the logic

   Either solution works. If we can come to a decision, I can even work on fixing it.
6. baltzell commented on May 1, 2026

   

   baltzell

   on May 1, 2026

   Collaborator

   More actions

   Looks like the 2 options are:

   1. change the bank schema to match the software
   2. change the software to match the schema

   Is this is the only bank schema downstream of DSTs containing direction cosines?
7. baltzell

   added this to the Pass 3 milestone on Oct 11, 2026
8. baltzell

   self-assigned this

   on Oct 27, 2026

Issue actions