Using NCrystal

At its core, NCrystal is a standalone library which, based on user-configuration choices and appropriate data files (see below), can provide information and modelling relevant to thermal neutron transport through crystals and other materials. This means that NCrystal provides both interaction cross sections and the capability to sample the final states arising from scattering events.

Intended to be as highly embeddable and widely useful as possible, NCrystal facilitates a variety of interfaces, so users might access its capabilities using whatever tool or interface is most suited for their needs:

• From Python code:
  • See a simplistic Python example, or refer to more in-depth tutorials in the Jupyter notebooks at https://github.com/mctools/ncrystal-notebooks
• From C++ code:
  • See C++ example
• From C code:
• From the command-line using the nctool command.
  • Run nctool --help for more instructions.
  • The ncrystal-config command provides information about the NCrystal installation.
  • A bunch of other command-line tools exist as well, all called something like ncrystal_xxx.
  • NOTE: that nctool used to be called ncrystal_inspectfile (and that later name is for now still a valid alias for nctool).
• From a simulation tool which already has NCrystal interfaces. This includes for instance
  • OpenMC: Refer to OpenMC instructions in the README file.
  • McStas: Refer to McStas instructions in the README file.
  • Geant4: Refer to Geant4 instructions in the README file and checkout an example.

A very important feature is that NCrystal provides a uniform string-based configuration syntax (see below), shared by all of the above interfaces. That means it is possible to investigate a material configuration in any of the contexts outlined above, before then proceeding to use it in another. For instance, it is possible to use standard NCrystal command line tools to quickly inspect and tune a material configuration before using the resulting material in a more complicated setup (perhaps inside an application such as OpenMC, Geant4, or McStas). Or, one might investigate a setup interactively with Python.

Additionally, NCrystal contains an ever expanding Python API with various NCrystal-related utilities. For examples of how to use this API, several Jupyter-Lab notebooks available are available in this repo.

Setting up

To start with, verify that NCrystal was found and is working correctly by running the command (NOTE: nctool used to be called ncrystal_inspectfile and that later name is for now still a valid alias for nctool):

nctool --test

Alternatively you can do the test from Python code as well:

import NCrystal as NC
NC.test()

If any of the preceeding tests fail, it might be that your installation of NCrystal needs to be activated, which can often be done by sourcing the setup.sh script found among the installed files in order to use it (you can put a line like . /somewhere/myncrystal/setup.sh in your .bashrc or other similar file to have this done always). You can then try to run the test above again.

Note that, once activated, you can get a summary of the paths etc. of your NCrystal installation by running:

ncrystal-config -s

For something a bit more visual, you can also try to visualise cross-sections and scatterings of polycrystalline (or, powdered) aluminium:

nctool Al_sg225.ncmat

You can also run nctool --browse to see a list of available files (and you should checkout the Data-library if you haven't done so already).

Uniform material configuration syntax

An NCrystal configuration string ("cfg-string" or "cfgstr" for short) specifying a given material, usually has the form:

"<DataFileName>;opt1=val1;opt2=val2;...;optn=valn"

First and foremost one must provide the name of a data-file in a supported format (mainly .ncmat, but also .laz, and .lau, and optionally also .nxs with the appropriate plugin), which contains information about the material. After that comes a list of options pertaining to the particular configuration in which the material is to be used. This could for instance be the material temperature, or (for single crystals) orientation and mosaicity.

To pick a data file, most users will probably want to start by visiting the NCrystal data library, which contains a large number of data files written and validated by the NCrystal developers, and includes plots and printouts of relevant information, validation against experimental data, etc. Once a file has been chosen, it can either be downloaded, or (given that the file is most likely already included with your NCrystal installation), just its name noted.

Note that cfg-strings defining multiphase materials have a slightly different syntax, as shown in an example below.

Examples of configuration strings

Here are some examples of configuration strings and their results:

• "Al_sg225.ncmat"

  Polycrystalline (powdered) aluminium at default temperature of room temperature (20C = 293.15K). The file Al_sg225.ncmat will be found if it resides in the current working directory, if it is in a directory pointed at with the environment variable NCRYSTAL_DATA_PATH, or if it was installed with NCrystal (like files from the data library are by default, although they might not reside as physical files on the system).

• "/some/path/Al_sg225.ncmat"

  Same, but specifying the file location via an absolute path.

• "Al_sg225.ncmat;temp=-100C", "Al_sg225.ncmat;temp=173.15K", "Al_sg225.ncmat;temp=173.15"

  Also polycrystalline aluminium, but now with a temperature of -100C=173.15K, here specified in three different ways (note that the default unit is kelvin).

• "Ni_sg225.ncmat;temp=50C;density=0.45x"

  Loosely (45%) packed powdered nickel at 50C)

• "Polyethylene_CH2.ncmat;density=0.95gcm3"

  Polyethylene with a tuned density value (the default would be 0.92g/cm^3).

• "gasmix::0.72xCO2+0.28xAr/massfractions/3bar/250K"

  An Ar-CO2 gas mixture. If /massfractions had not been explicitly requested, molar (=volume) fractions would have been assumed.

• "gasmix::air/-10C/0.8atm/0.30relhumidity"

  Another gas mixture, using the shorthand air for standard air. The /0.30relhumidity is used to embed a bit of water (H and O atoms), reflecting a 30% relative humidity.

• "Ge_sg227.ncmat;mos=20.0arcmin;dir1=@crys_hkl:5,1,1@lab:0,0,1;dir2=@crys_hkl:0,-1,1@lab:0,1,0"

  Single crystalline mosaic Germanium, which might be used in monochromators or analysers in a neutron instrument. The configuration of single crystals necessarily gets slightly more complicated, due to the need to specify the orientation of the crystal. This is done here by specifying that the normal of the (h,k,l)=(5,1,1) plane should point along the z-axis in the laboratory system, and the normal of the (h,k,l)=(0,-1,1) plane should point along the y-axis. By default, it results in an error if the angle between the specified directions in the crystal frame and the specified laboratory frame are not essentially identical. For simplicity, it is possible to increase this tolerance, when one is only interested in exact alignment of the primary direction (e.g. when one is only concerned with the primary reflection plane of a monochromator): specifying dirtol=180deg will relax the condition on the secondary direction maximally.

• "Al2O3_sg167_Corundum.ncmat;bragg=0"

  With a slight cost of realism, the bragg parameter set to 0 or false can be used to easily and efficiently simulate single crystalline beam filters, by simply assuming that the crystal is oriented so that the incoming neutrons never fulfil the Bragg condition for any planes. The result is a material in which only the non-Bragg (i.e. inelastic or incoherent) components of the cross-section play a role.

• "phases<0.1*PbS_sg225_LeadSulfide.ncmat&0.9*Epoxy_Araldite506_C18H20O3.ncmat>;temp=296K"

  This defines a multi-phase material, using the syntax "phases<FRAC1*CFG1&..&FRACN*CFGN>[;COMMONCFG]". Note that the indicated fractions are assumed to by volume fractions, and must sum to 1.

Full list of available parameters

The reference documentation for the parameters in the latest release is available at CfgRefDoc, with a full list of available parameters and their meaning.

For more background, the NCrystal framework paper (https://doi.org/10.1016/j.cpc.2019.07.015) describes the idea of configuration strings in details, but a few variables were introduced/changed in connection with the NCrystal v2.0.0 and v3.0.0 releases, as discussed briefly on Announcement-Release2.0.0 and Announcement-Release3.0.0.