Announcement Release2.0.0
After several years of investigations and prototyping, followed by almost a year of intense full time work on the actual implementation and fine-tuning of algorithms and interfaces, the NCrystal developers are very proud and excited to finally being able to present the NCrystal v2.0.0 release!
The main feature of this release is that it finally brings proper state-of-the-art inelastic physics to NCrystal. Additionally, also incoherent-elastic scattering was cleaned up and made self-consistent, so NCrystal v2.0.0 can truly be said to be the release in which NCrystal finally moves beyond its former focus on Bragg diffraction. Additionally and also for the first time, NCrystal can now support the modelling of certain non-crystalline materials (e.g. liquids).
The actual changes to NCrystal took place in ~500 commits touching many hundreds of files, and are far too vast to list here. However, the present page attempts to provide a short summary of user-facing changes concerning physics capabilities, the materials data library, and the syntax of NCrystal configuration strings.
- The foundation: Scattering kernels
- On-the-fly kernel generation from phonon DOS
- Updates to materials data library and the NCMAT Format
- Updates to material configuration strings
- Outlook
- Citing and acknowledging NCrystal
- References
It is under some assumptions (notably isotropic materials and the incoherent approximation - cf. [1, Section 2.4] and [2]), possible to describe inelastic scattering in isotropic materials via a single two-dimensional scattering function (or one such function for each element in case of polyatomic materials). Based on this, the highest quality modelling of inelastic neutron scattering is in most relevant applications with support for such physics (PHITS, OpenMC, MCNP, ...) implemented in terms of 2D grids of tabulated data. These so-called scattering kernels are usually loaded from pre-evaluated neutron data libraries such as ENDF.
Starting with this new release, all inelastic scattering in NCrystal is now also based on scattering kernels! Several options exists concerning the origin of these scattering kernels. Firstly, they can of course be directly embedded in the NCMAT files themselves (cf. NCMAT-format) which has the advantage of being able to use existing scattering kernels from other applications. However, such fixed kernels comes with a cost of increased file-size. Additionally, a given scattering kernel is valid at a specific temperature only, so in this case the NCMAT file in question can only be used for one particular temperature.
For the case of crystalline materials, there exists the superior possibility of instead having NCrystal generate the kernels on-the-fly for any temperature, as will be discussed in more details in other sections below. Other materials like liquids require the direct specification of a kernel (files for water and heavy water are now part of the standard NCrystal data library, see details further down). For convenience, NCrystal additionally ships with a command-line utility, ncrystal_endf2ncmat, which can be used to convert scattering kernels in ENDF format to NCMAT format. As a reference all scattering kernels from the ENDF/B-VIII.0 release were converted and made available in the ncrystal-extra repo (note: these unvalidated files were mass-converted and might lack details such as crystal structure and corrected density, and are therefore not part of the official data library).
Depending on the choice of variables, the scattering function can either be denoted S(q,ꞷ) or S(ɑ,ꞵ). Here, q is the scalar momentum transfer of the neutron and ꞷ (or rather ℏꞷ) is the energy lost by the neutron in the scattering. The S(ɑ,ꞵ) formalism captures the same information, but using dimensionless variables ɑ=(ℏ/2mkT)×q² and ꞵ=-ℏꞷ/kT (m is the neutron mass, k Boltzmann's constant, and T the temperature). In order to extract total inelastic cross sections from a scattering kernel, or to sample the outcome of a given scattering, one must consider only the parts of phase-space kinematically accessible to a given incoming neutron (see for instance the plot above, in which the region accessible to a 1Å neutron is indicated in orange). Numerical integration then yields the cross section curve. As far as sampling is concerned, NCrystal employs a novel algorithm [2] which has the advantage of being both more efficient and accurate than what has been traditionally used.
Due to the inability of tabulated data to cover an infinite region, there will always be some maximal neutron energy beyond which a given tabulated scattering kernel will lack information about parts of the kinematically accessible phase-space. NCrystal support inelastic scatterings for neutrons beyond this maximal energy, by essentially filling out the missing extreme parts of the scattering kernel using a carefully implemented quantum mechanical free-gas model (which is indeed the limiting behaviour of the scattering function).
Most of the scattering kernels in the nuclear community (including in the ENDF releases) were prepared using programmes such as LEAPR from NJOY [3], using a method due to A. Sjölander [4] to expand a 1D phonon Density Of State spectrum (a.k.a. Vibrational Density Of States = VDOS) into a full-blown scattering kernel at a particular temperature, while taking into account multi-phonon interactions. NCrystal now provides an open source implementation of Sjölander's method, carefully optimised with Fast Fourier Transform techniques and a custom dynamic readjustment of parameters after each phonon-order is processed. As a result, the expansion into a full-blown kernel can be done in mere milliseconds at initialisation time, and without any user provided parameters beyond the actual phonon DOS (which must be specified in the NCMAT files, cf. NCMAT-format).
This approach brings many advantages for dealing with crystalline materials in NCrystal, compared with the usual approach of requiring all kernels to be pre-calculated with external programmes:
- Data file sizes are tiny (kB) compared with files with scattering kernels (MB).
- Ability to work at any temperature requested by users.
- Tradeoff between computational resources and precision of created scattering kernels can be selected by users dynamically by a single overall "luxury" parameter, vdoslux. The default setting is likely to be suitable for most users, in that it is not only fast, it also provides kernels of higher granularity than those in ENDF/B-VIII.0.
- Phonon DOS curves are much more easily obtained than scattering kernels, and can often be found in publications or other literature. NCrystal includes a new command line utility, vdos2ncmat which can be used to fine-tune and prepare phonon DOS curves for inclusion in NCMAT files.
As in the past, it is still allowed to define crystalline materials by providing just the unit cell structure. This might be useful when a phonon DOS or scattering kernel is not available, and the user is anyway mostly interested in elastic physics. However, NCrystal v2.0.0 improves the inelastic scattering realism even for such materials. It does so by using an idealised phonon DOS curve (the Debye model), which is essentially a quadratic function until a cutoff. The cutoff is the phonon energy or frequency equivalent of the Debye temperature, and the Debye model essentially corresponds to a uniform distribution of phonon directions in the parts of 3D space allowed by the cutoff.
NCrystal feeds this idealised phonon DOS into the same machinery as any other user-provided phonon DOS, expanding into a scattering kernel and resulting in a self-consistent treatment of inelastic physics. Although this method can not realistically describe the detailed energy transfer distribution in single-phonon interactions, it still in general manages to describe scattering kinematics and multi-phonon physics reasonably well.
As the four performance plots with Beryllium Oxide below indicate, there is no degradation whatsoever from using phonon DOS curves as input over a pre-made ENDF/B-VIII.0 kernel. And this is despite the advantages mentioned above of the phonon DOS approach (in particular small file-sizes and ability to work with any temperature).
The fall-back treatment with a Debye model DOS is of course less realistic - especially concerning the modelling of energy transfers, but the plots below indicate that the cross section and angular distributions are actually rather reasonable approximations to the results from a direct kernel or DOS. This conclusion is naturally material dependent, and obviously the result is better when the actual DOS happens to be similar to a Debye Model DOS. But in any case, even the fall-back treatment with a Debye Model is a vast improvement over the modelling of inelastic scattering in NCrystal v1.0.0.
The NCMAT format has been more thoroughly documented (cf. NCMAT-format), and a new version, NCMAT v2, was introduced in order to support the new features (NCrystal continues to support existing NCMAT v1 files of course).
The data library has been not only updated, but also expanded and now covers 51 different materials:
- The 43 existing materials from NCrystal v1.0.0. So far, 18 of these have been updated with phonon DOS spectrums, in order to provide realistic inelastic physics. The remaining will be simulated with a Debye Model DOS spectrum, which although not as precise is still a large improvement over the behaviour in NCrystal v1.0.0.
- Beryllium oxide has been added, with both crystal structure and phonon DOS curves.
- Files for light (H2O) and heavy (D2O) water (files for room temperature included directly in the NCrysal release, files for 15 other temperatures are available in the ncrystal-extra repo). For non-standard conditions, the user might need to update the material densities hardcoded in the files (refer to the files themselves for details).
- As a side-benefit of the free-gas model work needed for scattering kernel extrapolations, 5 noble gasses at STP conditions (1atm, 273.15K) were added: He, Ne, Ar, Kr, Xe. For non-STP conditions, the user might need to update the material densities hardcoded in the files (refer to the files themselves for details).
- As mentioned above, the entire ENDF/B-VIII.0 release of scattering kernels was mass converted to NCMAT format and the results placed in the ncrystal-extra repo (note again: these unvalidated files were mass-converted and lack details such as crystal structure and corrected density).
A few changes were made in the v2.0.0 release to the format of NCrystal configuration strings (cf. [1, Section 5]), but it is expected that most users will find that the configuration strings previously used will continue to work in the future. As in the past, the comments in the file NCMatCfg.hh continues to be the most complete documentation of all available parameters. The most important changes for NCrystal v2.0.0 are:
- New boolean parameters coh_elas and incoh_elas can be used to respectively enable and disable the coherent elastic and incoherent elastic components. The parameter bragg is now simply an alias for the underlying parameter coh_elas. The pseudo-parameter elas can be used to simultaneously toggle both coh_elas and incoh_elas (i.e. put elas=0 to disable all elastic components).
- New parameter inelas can be used to either disable inelastic components (i.e. inelas=0) or influence how inelastic scattering should be modelled. For instance inelas=vdosdebye can be used to force the usage of the fall-back Debye Model DOS, ignoring any actually available DOS or scattering kernel. In order to (usually for testing or validation purpuses) model a material entirely as a free gas of unbound noninteracting atoms, one can use inelas=freegas;elas=0.
- The old parameter bkgd is now obsolete and partially phased out, mostly because it does not make much sense to use the term "background" to refer to inelastic and incoherent-elastic components. For backwards compatibility, it still exists as a pseudo-parameter which can only be assigned the values bkgd=0 or bkgd=none. Doing so is equivalent to inelas=0;incoh_elas=0.
- New integer parameter vdoslux which controls the amount of "luxury" used in the expansion from phonon DOS to a scattering kernel (the default, vdoslux=3, is expected to be suitable for almost all users).
As always, the list of open issues at GitHub provides some indications of possible future NCrystal developments, given manpower, interest, etc. However, a few items bears special mention at the time of writing (August, 2020), in no particular order:
-
Support more amorphous materials, including polyethylene and plexiglass. In principle these two could be added already, based on phonon DOS curves included in ENDF/B-VIII.0, but it needs to be verified that the strong incoherent quasy-elastic components of these materials are included in a consistent manner in NCrystal's inelastic and elastic components, lest double-counting or under-counting occurs.
-
Scattering kernels in NCMAT files must currently be in the S(ɑ,ꞵ) format. It is planned to allow specification in the S(q,ꞷ) format as well.
-
Better inclusion of NCrystal in some applications requires better support for Parallelism and Multithreading. Work on this feature will benefit from the fact that as of NCrystal v2.0.0, compilation requires C++11 (or later), in which concurrency is made part of the standard and thus platform independent.
-
Support for impure and multi-phase materials, allowing users more flexibility in material definitions and allowing multi-phase configuration at the NCrystal level.
-
Document Bragg models. Although available since NCrystal v1.0.0, the Bragg scattering models still need to be documented more thoroughly, and it is planned to publish a paper with more details.
-
Move development to github. Although completely open source and freely available at github, historic reasons means that NCrystal day-to-day development still takes place in repositories and build systems internal to the European Spallation Source. It is the plan to move everything fully to github in order to better interact with the wider community, but it is a somewhat non-trivial task since several development tools (like unit tests) are currently based on other internal infrastructure.
-
Coherent kernels: The incoherent approximation, i.e. that the scattering function for coherent-inelastic scattering can be approximated by the scattering function for incoherent-inelastic scattering, is in principle only approximate and might in particular fail for single-phonon scattering in some strongly coherent scattering materials (e.g. pyrolythic graphite). In principle most of the scattering kernel machinery introduced in NCrystal v2.0.0 could be reused to support the inclusion of coherent kernels as well, where such might be available.
Although reference [1] refers to NCrystal release v1.0.0, it is still considered the main reference of NCrystal, also for release v2.0.0 and beyond. However, for work explicitly benefitting from the inelastic physics in NCrystal, we would also ask that reference [2] is cited as well.
Such citations not only acknowledges our past work on NCrystal, it also helps ensuring our continued ability to keep improving and supporting it in the future. So please remember these citations in any publications concerning work benefitting from NCrystal.
For oral presentations, etc., we would of course also appreciate acknowledgements and links in one form or the other.
- [1] X.-X. Cai and T. Kittelmann, NCrystal: A library for thermal neutron transport, Computer Physics Communications 246 (2020) 106851, DOI:10.1016/j.cpc.2019.07.015
- [2] X.-X. Cai, T. Kittelmann, E. Klinkby, J.I. Márquez Damián, Rejection-based sampling of inelastic neutron scattering, Journal of Computational Physics 380 (2019) 400–407, DOI:10.1016/j.jcp.2018.11.043
- [3] "R.E. MacFarlane, et. al., The NJOY Nuclear Data Processing System, Version 2016, LA-UR-12-27079, DOI:10.2172/1338791
- [4] A. Sjölander, Multi-phonon processes in slow neutron scattering by crystals, Arkiv För fysik 14 (1958) 315-371.