Merge branch 'develop' into distribution-alias-sampling

docs/source/conf.py

@@ -247,7 +247,7 @@ napoleon_use_ivar = True
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
     'numpy': ('https://numpy.org/doc/stable/', None),
-    'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
-    'matplotlib': ('https://matplotlib.org/', None)
+    'matplotlib': ('https://matplotlib.org/stable/', None)
 }

docs/source/io_formats/settings.rst

@@ -32,6 +32,17 @@ standard deviation.
 
   *Default*: false
 
+-------------------------------------
+``<create_delayed_neutrons>`` Element
+-------------------------------------
+
+The ``<create_delayed_neutrons>`` element indicates whether delayed neutrons
+are created in fission. If this element is set to "true", delayed neutrons
+will be created in fission events; otherwise only prompt neutrons will be
+created.
+
+  *Default*: true
+
 -------------------------------------
 ``<create_fission_neutrons>`` Element
 -------------------------------------
@@ -732,6 +743,14 @@ attributes/sub-elements:
 
     *Default*: false
 
+  :mcpl:
+    If this element is set to "true", the source point file containing the
+    source bank will be written as an MCPL_ file name ``source.mcpl`` instead of
+    an HDF5 file. This option is only applicable if the ``<separate>`` element
+    is set to true.
+
+    *Default*: false
+
 ------------------------------
 ``<surf_source_read>`` Element
 ------------------------------
@@ -767,6 +786,16 @@ certain surfaces and write out the source bank in a separate file called
 
     *Default*: None
 
+  :mcpl:
+    An optional boolean which indicates if the banked particles should be
+    written to a file in the MCPL_-format instead of the native HDF5-based
+    format. If activated the output file name is changed to
+    ``surface_source.mcpl``.
+
+    *Default*: false
+
+    .. _MCPL: https://mctools.github.io/mcpl/mcpl.pdf
+
 ------------------------------
 ``<survival_biasing>`` Element
 ------------------------------

docs/source/methods/cross_sections.rst

@@ -178,6 +178,27 @@ been selected. There are three methods available:
             section data is loaded for a single temperature and is used in the
             unresolved resonance and fast energy ranges.
 
+------------------
+NCrystal materials
+------------------
+
+As an alternative of the standard thermal scattering treatment using
+:math:`S(\alpha,\beta)` tables, OpenMC allows to create materials using
+NCrystal_. In addition to the regular thermal elastic, and thermal inelastic
+processes, NCrystal allows the generation of models for materials that cannot
+currently included in ACE files such as oriented single crystals (see the
+`NCrystal paper`_), and further extend the physics `using plugins`_. Thermal
+scattering kernels are generated on the fly from dynamic and structural data, or
+loaded from :math:`S(\alpha,\beta)` tables converted from ENDF6 evaluations.
+These kernels are sampled in a direct way using a fast `rejection algorithm`_
+that does not require previous processing. A `large library`_ of materials is
+already included in the NCrystal distribution, and new materials can be easily
+defined from scratch in the `NCMAT format`_ or `combining existing files`_.
+
+The compositions of the materials defined in NCrystal are passed on to OpenMC
+all other reactions except for thermal neutron scattering are handled by
+continuous energy ACE libraries.
+
 ----------------
 Multi-Group Data
 ----------------
@@ -279,3 +300,10 @@ or even isotropic scattering.
 .. _ENDF/B data: https://www.nndc.bnl.gov/endf-b8.0/
 .. _Leppanen: https://doi.org/10.1016/j.anucene.2009.03.019
 .. _algorithms: http://ab-initio.mit.edu/wiki/index.php/Faddeeva_Package
+.. _NCrystal: https://github.com/mctools/ncrystal
+.. _NCrystal paper: https://doi.org/10.1016/j.cpc.2019.07.015
+.. _using plugins: https://doi.org/10.1016/j.cpc.2021.108082
+.. _rejection algorithm: https://doi.org/10.1016/j.jcp.2018.11.043
+.. _large library: https://github.com/mctools/ncrystal/wiki/Data-library
+.. _NCMAT format: https://github.com/mctools/ncrystal/wiki/NCMAT-format
+.. _combining existing files: https://github.com/mctools/ncrystal/wiki/Announcement-Release3.0.0#2-multiphase-materials

docs/source/pythonapi/data.rst

@@ -66,7 +66,7 @@ Core Functions
     decay_energy
     decay_photon_energy
     dose_coefficients
-    gnd_name
+    gnds_name
     half_life
     isotopes
     kalbach_slope

docs/source/usersguide/install.rst

@@ -271,6 +271,17 @@ Prerequisites
 
           cmake -DOPENMC_USE_DAGMC=on -DCMAKE_PREFIX_PATH=/path/to/dagmc/installation ..
 
+    * NCrystal_ library for defining materials with enhanced thermal neutron transport
+
+      Adding this option allows the creation of materials from NCrystal, which
+      replaces the scattering kernel treatment of ACE files with a modular,
+      on-the-fly approach. To use it `install
+      <https://github.com/mctools/ncrystal/wiki/Get-NCrystal>`_ and `initialize
+      <https://github.com/mctools/ncrystal/wiki/Using-NCrystal#setting-up>`_
+      NCrystal and turn on the option in the CMake configuration step:
+
+          cmake -DOPENMC_USE_NCRYSTAL=on ..
+
     * libMesh_ mesh library framework for numerical simulations of partial differential equations
 
       This optional dependency enables support for unstructured mesh tally
@@ -294,6 +305,7 @@ Prerequisites
 .. _MOAB: https://bitbucket.org/fathomteam/moab
 .. _libMesh: https://libmesh.github.io/
 .. _libpng: http://www.libpng.org/pub/png/libpng.html
+.. _NCrystal: https://github.com/mctools/ncrystal
 
 Obtaining the Source
 --------------------
@@ -362,6 +374,12 @@ OPENMC_USE_DAGMC
   should also be defined as `DAGMC_ROOT` in the CMake configuration command.
   (Default: off)
 
+OPENMC_USE_NCRYSTAL
+  Turns on support for NCrystal materials. NCrystal must be
+  `installed <https://github.com/mctools/ncrystal/wiki/Get-NCrystal>`_ and
+  `initialized <https://github.com/mctools/ncrystal/wiki/Using-NCrystal#setting-up>`_.
+  (Default: off)
+
 OPENMC_USE_LIBMESH
   Enables the use of unstructured mesh tallies with libMesh_. (Default: off)
 

docs/source/usersguide/materials.rst

@@ -101,6 +101,42 @@ you would need to add hydrogen and oxygen to a material and then assign the
 
 .. _usersguide_naming:
 
+-------------------------
+Adding NCrystal materials
+-------------------------
+
+Additional support for thermal scattering can be added by using NCrystal_. The
+:meth:`Material.from_ncrystal` class method generates a :class:`openmc.Material`
+object from an `NCrystal configuration string
+<https://github.com/mctools/ncrystal/wiki/Using-NCrystal#uniform-material-configuration-syntax>`_.
+Temperature, material composition, and density are passed from the configuration
+string and the `NCMAT file
+<https://github.com/mctools/ncrystal/wiki/NCMAT-format>`_ that define the
+material, e.g.::
+
+   mat = openmc.Material.from_ncrystal('Al_sg225.ncmat;temp=300K')
+
+defines a material containing polycrystalline alumnium,
+
+::
+
+   mat = openmc.Material.from_ncrystal("""Ge_sg227.ncmat;dcutoff=0.5;mos=40arcsec;
+                                           dir1=@crys_hkl:5,1,1@lab:0,0,1;
+                                           dir2=@crys_hkl:0,-1,1@lab:0,1,0""")
+
+defines an oriented germanium single crystal with 40 arcsec mosaicity.
+
+NCrystal only handles low energy neutron interactions. Other interactions are
+provided by standard ACE files. NCrystal_ comes with a `predefined library
+<https://github.com/mctools/ncrystal/wiki/Data-library>`_ but more materials can
+be added by creating NCMAT files or on-the-fly in the configuration string.
+
+.. warning:: Currently, NCrystal_ materials cannot be modified after they are created.
+             Density, temperature and composition should be defined in the
+             configuration string or the NCMAT file.
+
+.. _NCrystal: https://github.com/mctools/ncrystal
+
 ------------------
 Naming Conventions
 ------------------
@@ -222,3 +258,4 @@ been generated, you can tell OpenMC to use this file either by setting
    materials.cross_sections = '/path/to/cross_sections.xml'
 
 .. _MCNP: https://mcnp.lanl.gov/
+

docs/source/usersguide/scripts.rst

@@ -157,9 +157,9 @@ geometry.xml
   added. Any 'surfaces' attributes/elements on a cell will be renamed 'region'.
 
 materials.xml
-  Nuclide names will be changed from ACE aliases (e.g., Am-242m) to HDF5/GND
+  Nuclide names will be changed from ACE aliases (e.g., Am-242m) to HDF5/GNDS
   names (e.g., Am242_m1). Thermal scattering table names will be changed from
-  ACE aliases (e.g., HH2O) to HDF5/GND names (e.g., c_H_in_H2O).
+  ACE aliases (e.g., HH2O) to HDF5/GNDS names (e.g., c_H_in_H2O).
 
 ----------------------
 ``openmc-update-mgxs``

docs/source/usersguide/settings.rst

@@ -474,7 +474,6 @@ selected::
    Some features related to photon transport are not currently implemented,
    including:
 
-     * Tallying photon energy deposition.
      * Generating a photon source from a neutron calculation that can be used
        for a later fixed source photon calculation.
      * Photoneutron reactions.