mctools / ncrystal

NCrystal : A library for thermal neutron transport in crystals and other materials
----------------------------------------------------------------------------------

This is a source distribution of NCrystal, a library and associated tools which
enables calculations for Monte Carlo simulations of thermal neutrons in crystals
and other materials. Supported is a range of physics including both coherent,
incoherent, elastic and inelastic scatterings in a wide range of materials,
including crystal powders, mosaic single crystals, layered single crystals,
amorphous solids, and liquids. Multiphase materials or isotopically enriched
material are supported as well, and the framework furthermore supports
phase-contrast (SANS) physics. Written in C++, interfaces and infrastructure
facilitate integration into existing simulation frameworks such as Geant4
(https://geant4.web.cern.ch/) or McStas (http://mcstas.org/), as well as allowing
direct usage from C++, C or Python code or via command-line tools. While the C++
library is designed with a high degree of flexibility in mind for developers,
typical end-user configuration is deliberately kept simple and uniform across
various applications and APIs - this for instance allows tuning and validation
of a particular crystal setup to be performed in one tool before it is then
deployed in another.

In addition to code and tools, the NCrystal distribution also includes a set of
validated data files, covering many crystals important at neutron scattering
facilities. For more information about the properties and validity of each file,
users are referred to the dedicated page at
https://github.com/mctools/ncrystal/wiki/Data-library .

Supporting compilation with all modern C++ standards (C++11 and later), the code
has no third-party dependencies and is available under the highly liberal open
source Apache 2.0 license (see NOTICE and LICENSE files for usage conditions and
the INSTALL file for build and installation instructions). NCrystal was
developed in close collaboration by Xiao Xiao Cai (DTU, ESS) and Thomas
Kittelmann (ESS) and was supported in part by the European Union's Horizon 2020
research and innovation programme under grant agreement No 676548 (the
BrightnESS project) and 951782 (the HighNESS project)..

A very substantial effort went into developing NCrystal. If you use it for your
work, we would appreciate it if you would use the following primary reference in
your work:

  X.-X. Cai and T. Kittelmann, NCrystal: A library for thermal neutron
  transport, Computer Physics Communications 246 (2020) 106851,
  https://doi.org/10.1016/j.cpc.2019.07.015

For work benefitting from elastic physics (e.g. Bragg diffraction), we
furthermore request that you additionally also use the following reference in
your work:

  T. Kittelmann and X.-X. Cai, Elastic neutron scattering models
  for NCrystal, Computer Physics Communications 267 (2021) 108082,
  https://doi.org/10.1016/j.cpc.2021.108082

For work benefitting from our inelastic physics, we furthermore request that you
additionally also use the following reference in your work:

  X.-X. Cai, T. Kittelmann, et. al., "Rejection-based sampling of inelastic
  neutron scattering", Journal of Computational Physics 380 (2019) 400-407,
  https://doi.org/10.1016/j.jcp.2018.11.043

The rest of this file gives a brief overview of the manners in which NCrystal
capabilities can be utilised. Further instructions and documentation, along with
the latest version of NCrystal, can be found at https://mctools.github.io/ncrystal/



Using the NCrystal installation from the command-line
-----------------------------------------------------

After installing NCrystal and having sourced the setup.sh script mentioned in
the INSTALL file, you can run any of the commands from the $NCRYSTALDIR/bin
directory, which includes example code as well as the ncrystal_inspectfile
command. Start by reading the usage instructions:

$> ncrystal_inspectfile --help

Assuming you chose to install data files, you can try to let NCrystal load one
of the data files found in $NCRYSTALDIR/data/ (or provide the absolute path to a
data file downloaded from https://github.com/mctools/ncrystal/wiki/Data-library)
and either dump the derived information to the terminal...:

$> ncrystal_inspectfile --dump Al_sg225.ncmat

... or plot polycrystalline cross-sections and sampled scatter angles with:

$> ncrystal_inspectfile Al_sg225.ncmat



Using the NCrystal installation from C++ (including Geant4), C or Python code
-----------------------------------------------------------------------------

If you wish to use NCrystal from Python code, there is no special setup needed,
beyond sourcing the setup.sh script mentioned in the INSTALL file. If you on the
other hand wish to use NCrystal from your compiled C++ or C code, you must put
appropriate build flags. The recommended way is using CMake to do this (see next
section), but otherwise you must put the $NCRYSTALDIR/include directory in your
include path, usually by providing your compiler with an
"-I$NCRYSTALDIR/include" flag, and make sure you link to the NCrystal library in
$NCRYSTALDIR/lib, usually via "-L$NCRYSTALDIR/lib -lNCrystal" link flags. If
using the NCrystal-Geant4 interfaces, you should also add "-lG4NCrystal" to the
link flags.

Then, in your code you can access the relevant APIs with with statements like:

  #include "NCrystal/NCrystal.hh"     // C++ code, core NCrystal
  #include "G4NCrystal/G4NCrystal.hh" // C++ code, for Geant4 users
  #include "NCrystal/ncrystal.h"      // C code
  import NCrystal                     ## Python code

In the ./examples/ directory of your NCrystal distribution that you got after
downloading and unpacking the NCrystal source tar-ball, you will find small
examples of code using NCrystal. For C++/C and Geant4, there is currently no
documentation beyond the header files and examples. In the case of Python, there
is some integrated documentation via the usual "help" function, accessed with:

  import NCrystal
  help(NCrystal)



Configuring CMake-based projects to use NCrystal
------------------------------------------------

Assuming NCrystal was built and installed via CMake, it is possible and
recommended for client projects to simply use NCrystal as a CMake package in
order to correctly build their C/C++ code which depends on the NCrystal C++ or C
APIs.

Depending on where NCrystal was installed on the system, it might be necessary
to let CMake know about it via the usual mechanisms (for instance passing
-DNCrystal_DIR=/path/to/ncrystalinstall as an argument to cmake on the command
line).

CMake code for a small project using NCrystal might look like the following
(assume that exampleapp.cc below includes the NCrystal/NCrystal.hh header):

  cmake_minimum_required(VERSION 3.10...3.19)
  project(MyExampleProject LANGUAGES CXX)
  find_package(NCrystal REQUIRED)
  add_executable(exampleapp "${PROJECT_SOURCE_DIR}/exampleapp.cc")
  target_link_libraries( exampleapp NCrystal::NCrystal )
  install( TARGETS exampleapp DESTINATION bin )

If the NCrystal-Geant4 bindings are needed, they must be explicitly requested,
and the NCrystal::G4NCrystal target added as a dependency for downstream code:

  find_package(NCrystal REQUIRED COMPONENTS GEANT4BINDINGS )
  target_link_libraries( exampleapp NCrystal::G4NCrystal )

This will of course fail if NCrystal was not build with Geant4 support
(i.e. configured with -DBUILD_G4HOOKS=ON).



Using the NCrystal installation from McStas
-----------------------------------------------------------------------------

A sample component is provided for McStas, which embeds NCrystal material
simulations into simple shapes (currently boxes, cylinders and spheres),
allowing for highly realistic components representing samples, filters or
monochromators. The component and ncrystal scripts referenced below is already
available out of the box in McStas, but expert users can of course still
download and install a more recent NCrystal version with an existing McStas
installation. In any case, the NCrystal-McStas component must be made available
by running the following command in the directory from which McStas commands
will later be invoked:

$> ncrystal_preparemcstasdir

This sets up a symlinks to NCrystal_sample.comp file, as well as creating
necessary links to the NCrystal installation. It is then possible to use the
component in an instrument file, for instance setting up an r=1cm sphere with
powdered sapphire:

COMPONENT mysample = NCrystal_sample(cfg="Al2O3_sg167_Corundum.ncmat",radius=0.01)
AT (0, 0, 0) RELATIVE PREVIOUS

For more documentation about the NCrystal_sample component, run:

$> mcdoc NCrystal_sample

It should be noted that NCrystal can also be used as a physics backend for
McStas-Union geometries, due to Mads Bertelsen (ESS). It is possible to create
code turning NCrystal cfg-strings into Union material definitions, using the
NCrystal.mcstasutils Python module:

$> python3 -mNCrystal.mcstasutils --union my_Al 'Al_sg225.ncmat;temp=250K'