Coincident source

[cfichtlscherer]

Description

This pull request adds a CoincidentSource class that enables coincident particle emissions in fixed-source simulations. This allows, for example, the simulation of Co-60 summation peaks observed in gamma detectors.

The idea is that a source can now emit multiple particles per history. A CorincidentSource wraps several IndependentSource sub-sources that share the same spatial position and time but have independent particle types, energies, and angular distributions. The primary particle is created normally, and the coincident particles are passed directly into the secondary bank of that particle.

A per-sub-source emission probability can be set to control how often each coincident particle is created (e.g., a secondary gamma emitted only 50% of the time to represent branching ratios in decay schemes).

For tallies, each correlated particle carries its full weight. This means a single-source event can produce multiple counts in a tally, which is more intuitive than splitting the weight among correlated particles.

Example usage

  gamma1 = openmc.IndependentSource(
      energy=openmc.stats.Discrete([1.33e6], [1.0]),
      particle='photon'
  )
  gamma2 = openmc.IndependentSource(
      energy=openmc.stats.Discrete([1.17e6], [1.0]),
      particle='photon'
  )

  source = openmc.CoincidentSource(
      space=openmc.stats.Point((0, 0, 0)),
      sources=[gamma1, gamma2],
      probabilities=[1.0, 0.9988]
  )

Checklist

• I have performed a self-review of my own code
• I have run clang-format (version 15) on any C++ source files (if applicable)
• I have followed the style guidelines for Python source files (if applicable)
• 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]

I think CoincidentSource is a better name because CorrelatedSource reminds me of correlated probability distributions (for when we want to implement dependent probability distributions).
You also used that name in the pull request title and commit.

[GuySten]

Looks good to me!

[paulromano]

Putting a placeholder review -- I'd like to review this one in full before we merge