[Point Detector] Add relativistic kinematics and CM ↔ lab Jacobian

[itay-space]

Description

This PR is the second step in breaking down the point detector tally project into smaller, reviewable pieces, following the large PR #3109 and the paper Development and benchmarking of a point detector in OpenMC.

The first step in this series was [Point Detector] Add distribution get_pdf functionality (#3550). Building on that, this PR introduces relativistic kinematics functionality needed for transporting virtual particles towards the detector and handling frame transformations.

Changes in this PR:

• Added relativistic calculator for virtual particle motion towards detector
• Updated target velocity handling with v_t() accessors
• Introduced Jacobian for CM ↔ lab frame transformation
• Used neutron mass as placeholder (getMass() not yet implemented)

This keeps the scope focused and review manageable. Future PRs will continue to add further components of the point detector tally implementation.

Checklist

• [x] I have performed a self-review of my own code
• [x] I have run clang-format (version 15) on any C++ source files (if applicable)
• [x] I have followed the style guidelines for Python source files (if applicable)
• [x] I have made corresponding changes to the documentation (if applicable)
• [ ] I have added tests that prove my fix is effective or that my feature works (if applicable)

[GuySten]

@itay-space, I have a few suggestion:

I think i prefer the method mass() to be in this PR. It should be trivially extracted from speed(). Please update the original PR after i will merge the first PR next week. I do not like adding more data to particle data (v_t) I hope that we will manage without. So I prefer to remove it from the scope of this PR. I have no idea what either boostf or rel_scatt supposed to do. So I am asking for a reference for the maths of both of them. I hope we will manage to simplify the implementation.

[itay-space]

I added mass() using speed() and KE, and we need to keep v_t (target velocity) for proper COM transformations. I also added references for boostf (Lorentz boost) and rel_scatt (relativistic two-body scattering).

[itay-space]

@GuySten Thanks for the feedback! I just want to clarify that this part is actually one of the most crucial components for the point detector. To correctly evaluate the flux at the detector point, we need to solve the virtual particle kinematics and perform the transformation into the lab frame - that’s the frame where the probability density function is physically relevant.

I explained the methodology in the paper attached to the PR. I’d encourage you to have a look at it for the details. While it’s true that a classical implementation could also be done, that would restrict the method to low energies. The relativistic treatment is what ensures the point detector remains valid across the full energy range.

[GuySten]

Maybe I was not clear enough. openmc already has two-body classical kinematics. We can make the point detector code use the current kinematics for starters. And then in subsequent PRs implement a flag for turning all the kinematics in openmc to be relativistic and so the point detector could return relativistic kinematics results when the flag is turned on.

I believe the code could be structured in a way that the same code pathways that are used for the classical kinematics point detector will be used for the relativistic kinematics point detector so it will not add additional developer work.

[Orsfam]

Hi @GuySten , sorry for jumping on the wagon so late. I’m one of the original developers of the point detector project, and @itay-space asked me to weigh in.

Regarding your comment: I agree that adding a classical/relativistic flag would make sense for completeness. However, as @itay-space mentioned, it would require extra implementation.

Note that although OpenMC uses classical kinematics when sampling outgoing energy and direction, our case is a bit more complex. We need to determine the COM direction that correlates with the lab direction for the point detector, which is not easily reversible since it is energy-dependent.

Since the two formalisms are extremely similar within our energy ranges, I would suggest not going down that road.

[GuySten]

@itay-space, I thought to wait with continuing to review this PR until @paulromano review the previous PR. He might have critical feedback that will affect this PR also.