Starting with release 4.2.0, NCrystal ships with an ncmat2endf utility 1(#references) for automatic export of NCrystal models into the ENDF-6 format. This ENDF (Evaluated Nuclear Data File) format is the traditional data format used in the Nuclear Data community, and ncmat2endf thus exists as a service to users of any nuclear radiation transport codes that do not currently have a direct integration with NCrystal, but who nonetheless wishes to take advantage of the material composition tools and larger data library of NCrystal.

A few caveats are important to mention before proceeding:

• ENDF files usually require additional pre-processing with NJOY or other processing tools before they can be used by the radiation transport codes.
• Not all physics models supported by NCrystal can be shoe-horned into the venerable ENDF format. For the moment, the ncmat2endf tool thus primarily supports the conversion of standard single-phase materials where the dynamics are governed by phonon VDOS curves and the incoherent approximation is used for inelastic physics. These materials can be crystalline and contain Bragg diffraction, but see below for important notes concerning the limitation of elastic physics in ENDF files.
• The NCrystal algorithms consuming the modelling data, be it for Bragg diffraction or inelastic scattering, are optimised to reduce numerical artifacts and other unwanted effects. The conversion to an ENDF-based pipeline can therefore in general be expected to introduce more numerical artifacts in the final models.
• Data in ENDF files is valid at pre-determined temperatures only, while NCrystal in general supports a flexible run-time choice of temperature.

Due to the above caveats, it is always adviced that users rely on a direct integration with NCrystal instead when possible. This is for instance the case in applications like OpenMC, Geant4, and McStas, while users of codes like MCNP or PHITS will have to rely on the conversion to ENDF files discussed here.

The ncmat2endf utility replaces NJOY+NCrystal 2(#references), and is written in Python — relying on endf-parserpy 3(#references) to format and output the ENDF files, thus ensuring compatibility with the ENDF-6 format.

Input parameters

• The only strictly required parameter of ncmat2endf is an NCrystal cfg-string: A string defining the material to NCrystal, like "Al2O3_sg167_Corundum.ncmat;temp=350K". See the section about uniform material configuration on the Using NCrystal page for more information about such cfg-strings. Although materials typically have a default temperature, for the usage with ncmat2endf we recommend to always set a temperature value explicitly in the cfg-string, due to the importance of this parameter in the production of ENDF data.
• A name for the material. This is used to generate the filename of the output files, and can optionally be left out for monoatomic materials. As an example, processing Polyethylene_CH2.ncmat;temp=300K and giving it a name CH2, will cause the produced files to be named tsl_H_in_CH2.endf and tsl_C_in_CH2.endf.
• ENDF metadata. The ENDF-6 format contains several metadata fields that could be used to store information about the evaluated nuclear data library that will contain the file, its authors, production and distribution dates among other things. Such fields typically do not affect the subsequent processing of the data.
• Elastic mode: Unfortunately, ENDF files have historically not supported having both coherent-elastic and incoherent-elastic physics in the same file. Therefore, people generating ENDF files have been using various tricks to get around this limitation. The ncmat2endf utility supports three strategies for this (see 2(#references) for more details):
  • greater: only the "major" component of elastic scattering is saved. Specifically, coherent-elastic scattering is considered to be the "major" component if the bound coherent scattering length is greater than the bound incoherent scattering length, and vise versa.
  • scaled (the default): for single element materials, only the major elastic component is saved, and it is scaled to the total elastic cross section. For polyatomic systems, the element with the smallest incoherent cross section is used to store the coherent elastic component, and its incoherent elastic contribution is distributed among the other elements to match the total cross section of the compound.
  • mixed: both the coherent elastic and incoherent elastic components are saved. This option clearly has the highest accuracy, but unfortunately not all applications currently support this relatively recent addition to the ENDF format — which is why it is not currently the default option of ncmat2endf.

Python API

The Python API can be accessed by importing the NCrystal.ncmat2endf module. This provides the ncmat2endf(..) function, and the EndfMetaData class. The full API reference can be optained by:

import NCrystal.ncmat2endf
help( NCrystal.ncmat2endf )

As a simple example, here is how to export powdered aluminium. Notice how the return value of the function provides an overview of the produced file(s):

>>> from NCrystal.ncmat2endf import ncmat2endf
>>> r = ncmat2endf('Al_sg225.ncmat;temp=320K')
Initialise nuclear data...
Write ENDF file tsl_Al.endf ...
Files created:
  tsl_Al.endf : Al with fraction 1
Suggested material density: 2.698645518 g/cm^3
>>> print(r)
{'density': 2.6986455176922477, 'temperature': 320.0, 'files': [{'file': 'tsl_Al.endf', 'fraction': 1.0, 'component': 'Al'}]}

The EndfMetaData class can be used to provide the metadata fields of the ENDF-6 format (for the MF=1 / MT=451 ENDF section). Here is how we can use it to set the laboratory name to IAEA, the author to Marie Curie, and assign the ENDF material number 113 to Al. We will also set the evaluation, revision and distribution dates to the current month (June 2025). Finally, we use the material_name parameter to give our material a name:

>>> from NCrystal.ncmat2endf import ncmat2endf, EndfMetaData
>>> m = EndfMetaData( {'ALAB':'IAEA', 'AUTH': 'Marie Curie','MATNUM':{'Al':113}, } )
>>> m.set_value('LIBNAME','IAEA-TSL')
>>> m.set_all_dates_as_now()
>>> print(m)
EndfMetaData({"ALAB": "IAEA", "AUTH": "Marie Curie", "LIBNAME": "IAEA-TSL", "NLIB": 0, "REFERENCE": "REFERENCE", "LREL": 0, "NVER": 1, "MATNUM": {"Al": 113}, "ENDATE": "", "EDATE": "JUN25", "DDATE": "JUN25", "RDATE": "JUN25"})
>>> r = ncmat2endf('Al_sg225.ncmat;temp=293.6K', endf_metadata=m, material_name='Al-metal')
Initialise nuclear data...
Write ENDF file tsl_Al_in_Al-metal.endf ...
Files created:
  tsl_Al_in_Al-metal.endf : Al with fraction 1
Suggested material density: 2.698645518 g/cm^3
>>> print(r)
{'density': 2.6986455176922477, 'temperature': 293.6, 'files': [{'file': 'tsl_Al_in_Al-metal.endf', 'fraction': 1.0, 'component': 'Al'}]}
>>>

Command-line interface

The command-line interface (CLI) is provided by the ncrystal_ncmat2endf command. The full reference documentation can be optained by:

$> ncrystal_ncmat2endf --help

In general, the command-line interface provides the same functionality as the Python API described above. For instance, here is how one can export powdered aluminium:

$> ncrystal_ncmat2endf "Al_sg225.ncmat;temp=320K"

As in the Python API, it is also possible to obtain a dictionary object with an overview of the conversion. This can be achieved by the --index option, and will result in the creation of a file containing the dictionary encoded in JSON format:

$> ncrystal_ncmat2endf "Al_sg225.ncmat;temp=320K" --index results.json
Initialise nuclear data...
Write ENDF file tsl_Al.endf ...
Files created:
  tsl_Al.endf : Al with fraction 1
Suggested material density: 2.698645518 g/cm^3
Writing index file: results.json
$> cat results.json
{
    "density": 2.6986455176922477,
    "temperature": 320.0,
    "files": [
        {
            "file": "tsl_Al.endf",
            "fraction": 1.0,
            "component": "Al"
        }
    ]
}

Additionally, metadata can be modified via the --mdata, -m, and --now flags, and the --name flag can be used to set a material name:

$> ncrystal_ncmat2endf "Al_sg225.ncmat;temp=293.6K" --name "Al-metal" -f --now \
                       -m "ALAB:IAEA" -m "AUTH:Marie Curie" -m "MATNUM:Al:113" -m "LIBNAME:IAEA-TSL"
Initialise nuclear data...
Write ENDF file tsl_Al_in_Al-metal.endf ...
Files created:
  tsl_Al_in_Al-metal.endf : Al with fraction 1
Suggested material density: 2.698645518 g/cm^3

Advanced options

Both the CLI and the Python API contains several advanced options, that should in general be used with care. Some of these are:

• Options controlling the granularity and "luxury" of the produced inelastic scattering kernels. This is simply controlled via the standard NCrystal cfg-string vdoslux parameter. The default value (3) is likely a good choice for most applications, but it could be increased to 4 or 5 for more demanding materials, or reduced to 2 or even 1 if file sizes are crucial (however, this might come at a cost of increased numerical artifacts once the ENDF files are processed with e.g. NJOY).
• Options for multiple temperatures blocks in the produced ENDF files are available, but not recommended. This is because NCrystal computes an optimal (alpha, beta) grid for each material and temperature, while the ENDF format imposes the same grid on all temperatures. It is strongly recommended that users stick to specifying a single temperature per ENDF file, using the ;temp=...K syntax in the cfg-strings.
• Options for encoding asymmetric $S(\alpha, \beta)$ into the ENDF files: the default ENDF-6 format stores only one branch of the symmetrized $S(\alpha, \beta)$ table. The Python API option lasym= and the CLI arguments --totsab and --asymsab allow to save files in the non-symmetric format, which can be particularly useful for very-cold materials. However, note that this currently requires special versions of codes like NJOY in order to deal with such files.
• Options for the maximum neutron energy to be covered by the kernels. This defaults to 5.0eV, which is also the default implied by NCrystal's vdoslux=3 setting (the default). It might occasionally have to be lowered for very cold materials.
• Option for the minimum $S$-values to be stored in the scattering kernels. Values below this value (default 1e-100) will be stored as a pure 0.0 instead. This value-clipping is needed to avoid issues with subsequent processing in e.g. NJOY.

Jupyter notebook examples

A Jupyter notebook showing ncmat2endf in action is available in the ncrystal-notebooks repository (search for "Exporting materials as ENDF files" on the page). It can be viewed online, executed locally, or in the cloud. Please consult instructions at ncrystal-notebooks.

References

• [1] J.I. Marquez Damian, T. Kittelmann, D. Di Julio, S. Xu, D. Roubtsov and G. Muhrer. Open source pipelines for thermal scattering data generation: from NCrystal to ENDF-6, 16th Conference of Nuclear Data for Science and Technology, Madrid, June 2025.
• [2] K. Ramić, J.I. Marquez Damian, T. Kittelmann, D.D. Di Julio, D. Campi, M. Bernasconi, G. Gorini and V. Santoro. NJOY+NCrystal: An open-source tool for creating thermal neutron scattering libraries with mixed elastic support. Nuclear Instruments and Methods in Physics Research Section A: Accelerators, Spectrometers, Detectors and Associated Equipment, 1027, p.166227 (2022). DOI:10.1016/j.nima.2021.166227
• [3] G. Schnabel, D. L. Aldama, R. Capote, How to explain ENDF-6 to computers: A formal ENDF format description language, DOI:10.48550/arXiv.2312.08249. Documentation: https://endf-parserpy.readthedocs.io/