Announcement Release2.1.0

NCrystal v2.1.0 : It's time to get dirty!

The NCrystal developers are happy to announce the NCrystal v2.1.0 release. In addition to a slew of minor fixes and adjustments (see the CHANGELOG for details), it brings a few new major features. Firstly, flexible atomic definitions can make your materials "dirty" (impure or enriched). Secondly, new developers can get their hands dirty with new examples and features. Finally, NCMAT data no longer needs to reside in actual physical files.

Note that the patch release NCrystal v2.1.1 is essentially identical to NCrystal v2.1.0 discussed here (the only difference is a small bugfix for a potential compilation issue).

Flexible atomic definitions

First and foremost, NCrystal v2.1.0 introduces a high level of flexiblity in the definitions of the atoms in a material. Previously, only natural elements could be specified in NCMAT data, and the related physical constants (masses and neutron scattering lengths) were hard-coded inside NCrystal in an internal database. This internal database has now been expanded to include data for 261 specific isotopes, in addition to 88 natural elements, and if desired these can freely be used for custom compositions using the new @ATOMDB section of NCMAT data (cf. NCMAT-format). For instance, here is how to enrich boron to 95% boron-10 content:

@ATOMDB
  B is 0.95 B10 0.05 B11

and here is how one can inject trace impurities of chromium into the positions in a crystal lattice otherwise occupied by aluminium atoms:

@ATOMDB
  Al is 0.999 Al 0.001 Cr

For convenience, it is even possible to perform the atomic (re)definitions using the new atomdb configuration parameter (cf. NCMatCfg.hh), which means that one can perform isotopic enrichments or injections of impurities without having to copy and edit an entire file. Examples of such usage would be: "BoronCarbide.ncmat;atomdb=B is 0.95 B10 0.05 B11" and "Al2O3_sg167_Corundum.ncmat;atomdb=Al is 0.999 Al 0.001 Cr" (if you dont like to have spaces in your cfg strings, you can use semicolons instead).

A small word of warning is in order: There is of course no magic involved, and while it is technically possible to perform more drastic changes, i.e. completely replace all aluminium atoms with chromium atoms with a cfg string "Al_sg225.ncmat;atomdb=Al:is:Cr", the result would likely not make sense from a perspective of physics and chemistry. In this case for instance, it would force the crystal structure (including spacegroup and lattice parameters) of aluminium on chromium, which is not a realistic material.

Finally, it should be mentioned that it is now also possible to override, or provide, physical constants:

@ATOMDB
  Si    28.09u 0.41491fm 0.004b 0.171b#<--- overrides natural element data
  Si29  28.97649466525u 0.47fm 0.001b  0.101b #<--- overrides isotope data
  Rn222 222.018u -1.23fm 4.56b 7.89b #<--- provide missing isotope data

The four numbers in each line above are: mass, coherent scat. length, incoherent cross section, and capture cross section.

In-memory NCMAT data

So far NCMAT data has always been required to reside in physical files with the .ncmat extension. But, starting with NCrystal v2.1.0, it is now also possible for NCrystal to deal with such data exclusively from programme memory. For instance, here is how one can define NCMAT data for a custom aluminium crystal, register it with NCrystal, and finally use it like any other NCMAT file (here a Python example, but C/C++ APIs exist as well of course):

import NCrystal as NC
myalu="""NCMAT v3
@CELL
 lengths 4.05 4.05 4.05
 angles 90 90 90
@SPACEGROUP
  225
@ATOMPOSITIONS
  Al 0   1/2 1/2
  Al 0     0   0
  Al 1/2 1/2   0
  Al 1/2   0 1/2
@DEBYETEMPERATURE
  Al   410
"""
NC.registerInMemoryFileData("MyAl.ncmat",myalu)
NC.createInfo("MyAl.ncmat;dcutoff=1").dump()

Note that when registering the data, one must provide a virtual file-name, making it possibly to identify the registered data in other contexts where NCrystal would normally need the name of an .ncmat file. Previously registered content will simply be overriden (and related caches cleared) if a subsequent registerInMemoryFileData use the same virtual file-name.

Based on this new feature, the NCrystal CMake-based build and installation procedure has a new optional flag, -DEMBED_DATA=ON. This is disabled by default, but if enabled the installation will not include the physical .ncmat files from the standard data library. Instead, the contents of the files will be embedded into the final NCrystal library. Downstream users can still refer to the files using their original file-names in cfg strings, but the ability to embed NCMAT data in the binary might make life easier for developers wishing to use NCrystal as a backend in their applications, without dealing with the hassle of copying around physical NCMAT files.

Making it easier to extend NCrystal with new physics

As the project matures, more and more external developers are interested in providing physics models for NCrystal. However, until now such developers were required to create ugly hacks in core NCrystal code, in order to get parameters transferred from an NCMAT file and into the C++ class where they implement their new model. In the new NCMAT v3 format, such hacks are no longer necessary, since the format now allows for new @CUSTOM_ sections (cf. NCMAT-format), with free-form content:

@CUSTOM_MYNEWPHYSICSDATA
  #This section is needed for my great new physics model

  6.789 Xe 0.95 0x0003450 true
  1.0e-5 # some comment here

This custom data is then simply globbed up by NCrystal and provided internally to the custom C++ code as lists of strings. In the example above, there are two non-empty lines with 5 and 1 words respectively, so internally the users custom C++ code would get the data as a std::vector<std::vector<std::string>> with content {{"6.789","Xe","0.95,"0x0003450","true"},{"1.0e-5"}}. The custom code is of course then responsible for parsing that data to turn it into the values it needs (and should throw exceptions in case of syntax errors).

How to put all of this together, including how to register the custom physics model with the NCrystal framework, can admittedly be a bit confusing. For that reason, NCrystal now also includes a small but complete and self-contained example in the file examples/ncrystal_example_customphysics.cc. This example extends NCrystal with a (silly) new physics model for incoherent-elastic scattering, while keeping the usual inelastic and coherent-elastic physics.

Another new feature of NCrystal v2.1.0 is that the many internal header files from NCrystal are made available to custom code, and they can be included with include statements like:

#include "NCrystal/internal/NCMath.hh"

Although these internal files are considered, well, internal, and do not come with any sort of guarantee concerning long-term API stability, we have chosen to expose them like this to all external developers, since they provide a lot of useful utilities for math, numerical integration, vectors, matrices, random sampling of distributions, and so on. Not only will that hopefully make external development of new physics models more productive, it will also make it easier in case it is at some point decided to try to adopt the new models into the core NCrystal codebase.

Taken together, these efforts should make it much easier for external contributors to get started on extensions for NCrystal. It is planned in the future to try to stream-line the process further, by updating the NCrystal CMake code to make it a more automatic dependency, and by considering workflows and documentation further. It is still early days, and we learn as we go along :-)

Outlook

As always, the list of open issues at GitHub provides some indications of possible future NCrystal developments, given manpower, interest, etc. On the shortest time-scale, the next release of NCrystal is planned to focus on some long-overdue interface adjustments, which will make it easier to use NCrystal safely in a multi-threaded environment.

Citing and acknowledging NCrystal

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, v2.1.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. At the time of writing, we are about to submit a publication with details about the elastic physics in NCrystal (please get in touch if you are interested in the status of this).

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.

References

• [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