coincident source

[cfichtlscherer]

Description

This pull request adds a CorrelatedSource 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 CorrelatedSource 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.CorrelatedSource(
      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)

[paulromano]

@cfichtlscherer Thanks for this PR and I look forward to reviewing it. However, you will need to resubmit the PR from your own fork as outlined in our contribution guidelines rather than creating a branch on the openmc-dev organization.

[cfichtlscherer]

Sorry for that!