Merge branch 'openmc-dev:develop' into njoy-photonuclear

Author: GuySten

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: CI
+name: Tests and Coverage
 
 on:
   # allows us to run workflows manually
@@ -21,7 +21,25 @@ env:
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
 jobs:
+  filter-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      source_changed: ${{ steps.filter.outputs.source_changed }}
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4
+      - name: Examine changed files
+        id: filter
+        uses: dorny/paths-filter@668c092af3649c4b664c54e4b704aa46782f6f7c # latest master commit, not released yet
+        with:
+          filters: |
+            source_changed:
+              - '!docs/**'
+              - '!**/*.md'
+          predicate-quantifier: 'every'
   main:
+    needs: filter-changes
+    if: ${{ needs.filter-changes.outputs.source_changed == 'true' }}
     runs-on: ubuntu-22.04
     strategy:
       matrix:
@@ -154,7 +172,7 @@ jobs:
           path: |
             ~/nndc_hdf5
             ~/endf-b-vii.1
-          key: ${{ runner.os }}-build-xs-cache
+          key: ${{ runner.os }}-build-xs-cache-${{ hashFiles(format('{0}/tools/ci/download-xs.sh', github.workspace)) }}
 
       - name: before
         shell: bash
@@ -186,6 +204,7 @@ jobs:
             --gcov-ignore-errors source_not_found \
             --gcov-ignore-errors output_error \
             --gcov-ignore-parse-errors suspicious_hits.warn \
+            --merge-mode-functions=separate \
             --print-summary \
             --lcov -o coverage-cpp.lcov || true
 
@@ -204,12 +223,33 @@ jobs:
           flag-name: C++ and Python
           path-to-lcov: coverage.lcov
 
-  finish:
-    needs: main
+  coverage:
+    needs: [filter-changes, main]
+    if: ${{ always() }}
     runs-on: ubuntu-latest
     steps:
       - name: Coveralls Finished
+        if: ${{ needs.filter-changes.outputs.source_changed == 'true' }}
         uses: coverallsapp/github-action@v2
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           parallel-finished: true
+
+  ci-pass:
+    needs: [filter-changes, main, coverage]
+    name: Check CI status
+    if: ${{ always() }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check CI status
+        run: |
+          if [[ "${{ needs.filter-changes.outputs.source_changed }}" == "false" ]]; then
+            echo "Documentation-only change - CI skipped successfully"
+            exit 0
+          fi
+          if [[ "${{ needs.main.result }}" == "success" && "${{ needs.coverage.result }}" == "success" ]]; then
+            echo "CI passed"
+            exit 0
+          fi
+          echo "CI failed"
+          exit 1

AGENTS.md

@@ -31,6 +31,24 @@ C++17/Python codebase where:
 - **Depletion**: `openmc.deplete` implements burnup via operator-splitting with various integrators (Predictor, CECM, etc.)
 - **Nuclear Data**: `openmc.data` provides programmatic access to nuclear data files (ENDF, ACE, HDF5)
 
+## Git Branching Workflow
+
+OpenMC uses a git flow branching model with two primary branches:
+
+- **`develop` branch**: The main development branch where all ongoing development takes place. This is the **primary branch against which pull requests are submitted and merged**. This branch is not guaranteed to be stable and may contain work-in-progress features.
+- **`master` branch**: The stable release branch containing the latest stable release of OpenMC. This branch only receives merges from `develop` when the development team decides a release should occur.
+
+### Instructions for Code Review
+
+When analyzing code changes on a feature or bugfix branch (e.g., when a user asks "what do you think of these changes?"), **compare the branch changes against `develop`, not `master`**. Pull requests are submitted to merge into `develop`, so differences relative to `develop` represent the actual proposed changes. Comparing against `master` will include unrelated changes from other features that have already been merged to `develop`.
+
+### Workflow for contributors
+
+1. Create a feature/bugfix branch off `develop`
+2. Make changes and commit to the feature branch
+3. Open a pull request to merge the feature branch into `develop`
+4. A committer reviews and merges the PR into `develop`
+
 ## Critical Build & Test Workflows
 
 ### Build Dependencies

docs/source/io_formats/depletion_results.rst

@@ -34,6 +34,7 @@ The current version of the depletion results file format is 1.2.
 
 :Attributes: - **index** (*int*) -- Index used in results for this material
              - **volume** (*double*) -- Volume of this material in [cm^3]
+             - **name** (*char[]*) -- Name of this material
 
 **/nuclides/<name>/**
 

docs/source/io_formats/geometry.rst

@@ -316,9 +316,10 @@ the following attributes or sub-elements:
     *Default*: None
 
   :orientation:
-    The orientation of the hexagonal lattice. The string "x" indicates that two
-    sides of the lattice are parallel to the x-axis, whereas the string "y"
-    indicates that two sides are parallel to the y-axis.
+    The orientation of the hexagonal lattice. The string "x" indicates that each
+    lattice element has two faces that are perpendicular to the x-axis, whereas
+    the string "y" indicates that each lattice element has two faces that are
+    perpendicular to the y-axis.
 
     *Default*: "y"
 

docs/source/io_formats/settings.rst

@@ -277,6 +277,15 @@ ignored for all run modes other than "eigenvalue".
 
   *Default*: 1
 
+------------------------------
+``<ifp_n_generation>`` Element
+------------------------------
+
+The ``<ifp_n_generation>`` element indicates the number of generations to
+consider for the Iterated Fission Probability method.
+
+  *Default*: 10
+
 ----------------------
 ``<inactive>`` Element
 ----------------------
@@ -402,7 +411,25 @@ then, OpenMC will only use up to the :math:`P_1` data.
 ``<max_history_splits>`` Element
 --------------------------------
 
-The ``<max_history_splits>`` element indicates the number of times a particle can split during a history.
+The ``<max_history_splits>`` element indicates the number of times a particle
+can split during a history.
+
+  *Default*: 1000
+
+-----------------------------
+``<max_secondaries>`` Element
+-----------------------------
+
+The ``<max_secondaries>`` element indicates the maximum secondary bank size.
+
+  *Default*: 10000
+
+------------------------
+``<max_tracks>`` Element
+------------------------
+
+The ``<max_tracks>`` element indicates the maximum number of tracks written to a
+track file (per MPI process).
 
   *Default*: 1000
 
@@ -844,13 +871,18 @@ attributes/sub-elements:
       relative source strength of each mesh element or each point in the cloud.
 
     :volume_normalized:
-      For "mesh" spatial distrubtions, this optional boolean element specifies
+      For "mesh" spatial distributions, this optional boolean element specifies
       whether the vector of relative strengths should be multiplied by the mesh
       element volume. This is most common if the strengths represent a source
       per unit volume.
 
       *Default*: false
 
+    :bias:
+      For "mesh" and "cloud" spatial distributions, this optional element
+      specifies floating point values corresponding to alternative probabilities
+      for each value/component to use for biased sampling.
+
   :angle:
     An element specifying the angular distribution of source sites. This element
     has the following attributes:
@@ -883,6 +915,10 @@ attributes/sub-elements:
       are those of a univariate probability distribution (see the description in
       :ref:`univariate`).
 
+    :bias:
+      For "isotropic" angular distributions, this optional element specifies a
+      "mu-phi" angular distribution used for biased sampling.
+
   :energy:
     An element specifying the energy distribution of source sites. The necessary
     sub-elements/attributes are those of a univariate probability distribution
@@ -906,6 +942,10 @@ attributes/sub-elements:
     mesh element and follows the format for :ref:`source_element`. The number of
     ``<source>`` sub-elements should correspond to the number of mesh elements.
 
+  .. note:: Biased sampling can be applied to the spatial and energy distributions
+            of a source by using the ``<bias>`` sub-element (see
+            :ref:`univariate` for details on how to specify bias distributions).
+
   :constraints:
     This sub-element indicates the presence of constraints on sampled source
     sites (see :ref:`usersguide_source_constraints` for details). It may have
@@ -998,13 +1038,26 @@ variable and whose sub-elements/attributes are as follows:
   *Default*: histogram
 
 :pair:
-  For a "mixture" distribution, this element provides a distribution and its corresponding probability.
+  For a "mixture" distribution, this element provides a distribution and its
+  corresponding probability.
 
   :probability:
-    An attribute or ``pair`` that provides the probability of a univariate distribution within a "mixture" distribution.
+    An attribute or ``pair`` that provides the probability of a univariate
+    distribution within a "mixture" distribution.
 
   :dist:
-    This sub-element of a ``pair`` element provides information on the corresponding univariate distribution.
+    This sub-element of a ``pair`` element provides information on the
+    corresponding univariate distribution.
+
+:bias:
+  This optional element specifies a biased distribution for importance sampling.
+  For continuous distributions, the ``bias`` element should contain another
+  univariate distribution with the same support (interval) as the parent
+  distribution. For discrete distributions, the ``bias`` element should contain
+  floating point values corresponding to alternative probabilities for each
+  value/component to be used for biased sampling.
+
+  *Default*: None
 
 ---------------------------------------
 ``<source_rejection_fraction>`` Element
@@ -1352,6 +1405,15 @@ has the following attributes/sub-elements:
               for fixed source and small criticality calculations, but is very
               optimistic for highly coupled full-core reactor problems.
 
+-------------------------------------
+``<uniform_source_sampling>`` Element
+-------------------------------------
+
+The ``<uniform_source_sampling>`` element indicates whether to sample among
+multiple sources uniformly, applying their strengths as weights to sampled
+particles.
+
+  *Default*: False
 
 ------------------------
 ``<ufs_mesh>`` Element
@@ -1364,6 +1426,16 @@ Agency Monte Carlo Performance Benchmark Problem," Proceedings of *Physor 2012*,
 Knoxville, TN (2012). The mesh should cover all possible fissionable materials
 in the problem and is specified using a :ref:`mesh_element`.
 
+-------------------------------
+``<use_decay_photons>`` Element
+-------------------------------
+
+The ``<use_decay_photons>`` element indicates whether to produce decay photons
+from neutron reactions instead of prompt photons. This is used in conjunction
+with the direct 1-step method for shutdown dose rate calculations.
+
+  *Default*: False
+
 .. _verbosity:
 
 -----------------------
@@ -1594,3 +1666,21 @@ following sub-elements/attributes:
 
   The ``weight_windows_file`` element has no attributes and contains the path to
   a weight windows HDF5 file to load during simulation initialization.
+
+-------------------------------
+``<weight_windows_on>`` Element
+-------------------------------
+
+  The ``weight_windows_on`` element indicates whether weight windows are
+  enabled.
+
+  *Default*: False
+
+----------------------------------
+``<write_initial_source>`` Element
+----------------------------------
+
+  The ``write_initial_source`` element indicates whether to write the initial
+  source distribution to file.
+
+  *Default*: False

docs/source/methods/variance_reduction.rst

@@ -22,12 +22,14 @@ not experience a single scoring event, even after billions of analog histories.
 Variance reduction techniques aim to either flatten the global uncertainty
 distribution, such that all regions of phase space have a fairly similar
 uncertainty, or to reduce the uncertainty in specific locations (such as a
-detector). There are two strategies available in OpenMC for variance reduction:
-the Monte Carlo MAGIC method and the FW-CADIS method. Both strategies work by
-developing a weight window mesh that can be utilized by subsequent Monte Carlo
-solves to split particles heading towards areas of lower flux densities while
-terminating particles in higher flux regions---all while maintaining a fair
-game.
+detector). There are three strategies available in OpenMC for variance
+reduction: weight windows generated via the MAGIC method or the FW-CADIS method,
+and source biasing. Both weight windowing strategies work by developing a mesh
+that can be utilized by subsequent Monte Carlo solves to split particles heading
+towards areas of lower flux densities while terminating particles in higher flux
+regions. In contrast, source biasing modifies source site sampling behavior to
+preferentially track particles more likely to reach phase space regions of
+interest.
 
 ------------
 MAGIC Method
@@ -132,3 +134,71 @@ aware of this.
     :label: variance_fom
 
     \text{FOM} = \frac{1}{\text{Time} \times \sigma^2}
+
+.. _methods_source_biasing:
+
+--------------
+Source Biasing
+--------------
+
+In contrast to the previous two methods that introduce population controls
+during transport, source biasing modifies the sampling of the external source
+distribution. The basic premise of the technique is that for each spatial,
+angular, energy, or time distribution of a source, an additional distribution
+can be specified provided that the two share a common support (set of points
+where the distribution is nonzero). Samples are then drawn from this "bias"
+distribution, which can be chosen to preferentially direct particles towards
+phase space regions of interest. In order to avoid biasing the tally results,
+however, a weight adjustment is applied to each sampled site as described below.
+
+Assume that the unbiased probability density function of a random variable
+:math:`X:x \rightarrow \mathbb{R}` is given by :math:`f(x)`, but that using the
+biased distribution :math:`g(x)` will result in a greater number of particle
+trajectories reaching some phase space region of interest. Then a sample
+:math:`x_0` may be drawn from :math:`g(x)` while maintaining a fair game,
+provided that its weight is adjusted as:
+
+.. math::
+    :label: source_bias
+
+    w = w_0 \times \frac{f(x_0)}{g(x_0)}
+
+where :math:`w_0` is the weight of an unbiased sample from :math:`f(x)`,
+typically unity.
+
+Returning now to Equation :eq:`source_bias`, the requirement for common support
+becomes evident. If :math:`\mathrm{supp} (g)` fully contains but is not
+identical to :math:`\mathrm{supp} (f)`, then some samples from :math:`g(x)` will
+correspond to points where :math:`f(x) = 0`. Thus these source sites would be
+assigned a starting weight of 0, meaning the particles would be killed
+immediately upon transport, effectively wasting computation time. Conversely, if
+:math:`\mathrm{supp} (g)` is fully contained by but not identical to
+:math:`\mathrm{supp} (f)`, the contributions of some regions outside
+:math:`\mathrm{supp} (g)` will not be counted towards the integral, potentially
+biasing the tally. The weight assigned to such points would be undefined since
+:math:`g(x) = \mathbf{0}` at these points.
+
+When an independent source is sampled in OpenMC, the particle's coordinate in
+each variable of phase space :math:`(\mathbf{r},\mathbf{\Omega},E,t)` is
+successively drawn from an independent probability distribution. Multiple
+variables can be biased, in which case the resultant weight :math:`w` applied to
+the particle is the product of the weights assigned from all sampled
+distributions: space, angle, energy, and time, as shown in Equation
+:eq:`tot_wgt`.
+
+.. math::
+    :label: tot_wgt
+
+    w = w_r \times w_{\Omega} \times w_E \times w_t
+
+Finally, source biasing and weight windows serve different purposes. Source
+biasing changes how particles are born, allowing the initial source sites to be
+sampled preferentially from important regions of phase space (space, angle,
+energy, and time) with an accompanying weight adjustment. Weight windows, by
+contrast, apply population control during transport (splitting and Russian
+roulette) to help particles reach and contribute in important regions as they
+move through the system. Because particle transport proceeds as usual after a
+biased source is sampled, particle attenuation in optically thick regions
+outside the source volume will not be affected by source biasing; in such
+scenarios, transport biasing techniques such as weight windows are often more
+effective.