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'