Format: NDI

Nautilus provides bidirectional conversion between EntityTag and several formats [1-6] defined by NDI (the Nuclear Data Interface library): SZA, FPID, zaid, and short string.

NDI maintains a suite of “libraries” as the data sets they maintain evolve over time. Each library consists of a number of “tables”. The mapping from library to table is not unique: some libraries use multiple tables, and some tables appear in multiple libraries. Some details of some NDI formats depend on which library/table is being used, so Nautilus allows the user to specify the library or table in order to control how the SZA, FPID, and zaid are generated. The library name is a string with no standard format. The table ID is a string of three digits followed by the letters “nm”; because the letters are always the same in this context, Nautilus can use the full table ID or simply the three-digit number part of the table ID. In order to tell Nautilus which library or table you are using, Nautilus will accept the following inputs:

• Library name as a std::string

• Table ID without the trailing letters as an int

• Table ID without the trailing letters as a double

  • The table ID often appears as a suffix following a period. For that reason, some users have taken to identifying the table as a decimal equal to the integer form of the table ID divided by 1,000.

  • Due to floating-point truncation issues, this method is not recommended. It is provided to support customers already using such a convention.

• Table ID as a std::string, either with or without the letter(s) at the end of the suffix

  • In the string format, the numerical part of the table ID must be a three-digit value, padded with leading zeroes.

If no library or table ID is specified, Nautilus defaults to some preferred variant (usually the most-common and/or most-modern variant).

NDI SZA

The NDI SZA is an integer format (datatype int in Nautilus) that primarily represents nuclides, but have special cases for a few particles.

The conversion routines available for this format are

• from_NDI_SZA that takes an SZA and returns an EntityTag

• to_NDI_SZA that takes an EntityTag and optionally a library or table ID, then returns an SZA

  • The possible ways to indicate a library or table ID are listed at the top of this page

Nuclides, by default, are encoded as integers according to

\[\text{SZA} = S \times 1{,}000{,}000 + Z \times 1{,}000 + A,\]

where \(S\) is the metastable state index, \(Z\) is the atomic number, and \(A\) is the atomic mass number. This arrangement of \(S\), \(Z\), and \(A\) gives rise to the name “SZA”.

As with many formats used at LANL, americium-242 has issues for historical reasons.

• The ground state and first metastable state are reversed, so:

  • 95242 should be the ground state but is actually the first metastable state.

  • 1095242 should be the first metastable state but is actually the ground state.

• Certain libraries / tables used an older notation, where 95042 means the ground state

  • When reading the NDI SZA, Nautilus will accept either 95042 or 1095242 to mean the ground state of americium-242.

  • When generating the NDI SZA, Nautilus allows an optional argument to specify the library or table ID (see the top of this page for details). Nautilus maintains a list of which libraries and table use the outdated 95042, and will generate the appropriate value (95042 or 1095242) depending on the specified library or table. If no argument is provided, Nautilus will default to 1095242.

Additionally, the NDI SZA has issues with americium-244. The ground and first metastable states are not reversed for americium-244, but it does have two different values for the first metastable state: 1095244 and 95044. Similarly to americium-242, Nautilus maintains a list of the libraries and tables that use the outdated 95044 in order to translate an EntityTag into an SZA, but will default to 1095244 if no library or table identifier is provided. When translating from an SZA to an EntityTag, Nautilus will accept either 1095244 or 95044.

The libraries and tables that use the outdated values (95042 and 95044) are listed in the table below. Some libraries and tables have both the outdated value and the new value for one or both of the nuclides in question. Nautilus only generates the outdated value if that is the only value available in the library or table. Any libraries or tables not listed here are assumed to use the values 1095242 and 1095244.

NDI library	table ID	Am-242g SZA in NDI	Am-242g SZA from Nautilus	Am-244m1 SZA in NDI	Am-244m1 SZA from Nautilus
endf7act	700nm	95042 and 1095242	1095242	95044	95044
mendf70x	701nm	95042	95042	1095244	1095244
mtmg01	121nm - 135nm	95042	95042	not present	1095244
mtmg01ex	121nm - 135nm	95042	95042	not present	1095244

The NDI SZA supports elementals by setting \(S\) and \(A\) both to zero. For example, 26000 is the iron elemental.

The NDI SZA supports two particles:

• photons are encoded as 0

• neutrons are encoded as 1

An EntityTag for a proton will be automatically translated to H-1 (SZA = 1001). That makes this format slightly lossy: EntityTag(proton) becomes SZA 1001, and then converting back to EntityTag gives the H-1 nuclide.

User-defined entities are not supported by the NDI SZA format, so when translating from EntityTag to SZA you get the same result as an unknown tag: invalid_ndi_sza, which has a value of -1.

NDI FPID

The FPID is the “floating-point identifier” format (datatype double in Nautilus). This is not a “standard” NDI format, but is a variation that is used in some projects. Due to floating-point truncation issues, this format is not recommended. It is only provided in order to support customers who already use this format.

The conversion routines available for this format are

• from_NDI_FPID that takes an FPID and returns an EntityTag

• to_NDI_FPID that takes an EntityTag and a table ID, then returns an FPID

  • Unlike the SZA, this format explicitly includes a table ID, so the table_id argument is required.

  • Because the mapping between libraries and table IDs is not unique, this format specifically requires a table ID and will not accept a library name.

  • The table ID can be provided using the various formats described at the top of this page.

The NDI FPID is simply an extension of the SZA value with the numerical part of the table ID appended as a suffix. So the format looks like SZA.###, and then this is translated into a floating-point value. Otherwise, all details of the SZA apply to the FPID.

Unknown or unsupported values will be translated to the special value invalid_ndi_fpid, which has the value of std::numeric_limits<double>::max().

NDI Zaid

The zaid is the “most complete” identifier for NDI. The name originally derives from \(Z\), \(A\), and table ID. It is a string-based format (datatype std::string in Nautilus). As with the FPID format, it is an extension of the SZA. The zaid is “SZA.tableID”, where the table ID is the full five-character format. Otherwise, all details of the SZA apply to the zaid.

The conversion routines available for this format are

• from_NDI_zaid that takes an FPID and returns an EntityTag

• to_NDI_zaid that takes an EntityTag and a table ID, then returns a zaid

  • Unlike the SZA, this format explicitly includes a table ID, so the table_id argument is required.

  • Because the mapping between libraries and table IDs is not unique, this format specifically requires a table ID and will not accept a library name.

  • The table ID can be provided using the various formats described at the top of this page. Nautilus can infer the trailing characters if a numerical format is used.

Unknown or unsupported values will be translated to the special value invalid_ndi_zaid, which has the value of “unknown”.

NDI Short String

The NDI short string is a compact string-based notation used in NDI, especially for things like the names of reactions. In Nautilus, it uses the datatype std::string. It is closely related to the short standard name and the IC chemsym formats.

The conversion routines available for this format are

• from_NDI_short_string that takes a short string and returns an EntityTag

• to_NDI_short_string that takes an EntityTag and returns a short string

  • Unlike the SZA, FPID, and zaid formats, the short string does not depend on the library or table, so it does not accept a library or table ID argument

Nuclides mostly are the IUPAC atomic symbol (in all lowercase letters) followed by the atomic mass number. So, for example: “w184” or “si28”.

This format does not permit any metastable state notation, so an EntityTag with a non-ground-state nuclide will return the invalid value. The exception is Am-242. As with other NDI formats, Am-242g and Am-242m1 are swapped. Therefore an NDI short string of “am242” refers to Am-242m1, and Am-242g cannot be represented as an NDI short string.

A few nuclides have special symbols:

• H-1 is represented as “p”

• H-2 is represented as “d”

• H-3 is represented as “t”

• He-4 is represented as “a”

Nautilus will accept “h1”, “h2”, “h3”, and “he4” on input, but generates the special symbols listed here.

The NDI short string format does not support elementals, so those will map to the invalid value.

Only two particles are supported by the NDI short string format

• photons are represented as either “g” or “g0”

  • Nautilus will generate “g” but will also accept “g0”

• neutrons are represented as “n”

  • because the NDI short string does not support elementals, there is no ambiguity between a neutron and a nitrogen elemental

An EntityTag for a proton will be automatically translated to H-1 (short string = “p”). That makes this format slightly lossy: EntityTag(proton) becomes short string “p”, and then converting back to EntityTag gives the H-1 nuclide.

User-defined entities are not supported by the NDI short string format, so they will generate the invalid value.

The invalid short string is given by invalid_ndi_short_string, which has the value “?”.

Notes and References

TODO: I still need to verify where/how to cite which documents.

[1]: “NDI Reference Manual 2.0.11” (https://xweb.lanl.gov/projects/data/nuclear/ndi/pdfs/NDIrefman2.0.11.pdf)

[2]: “Production-Depletion Chain Data Sets for MENDF71X”; Lee; Los Alamos National Laboratory memorandum XCP-5:12-033.

[3]: “Production-Depletion Chain Data Sets for ENDF7ACT”; Lee; Los Alamos National Laboratory memorandum XCP-5:11-020.

[4]: “Production-Depletion Chain Data Sets for MENDF70X”; Lee; Los Alamos National Laboratory memorandum XCP-5:11-037.

[5]: “ENDF70: A Continuous-Energy MCNP Neutron Data Library Based on ENDF/B-VII.0”; Trellue, Little, White, MacFarlane, Kahler; Los Alamos National Laboratory technical report LA-UR-08-2000.

[6]: “Release of ENDF/B-VIII.0-Based ACE Data Files”; Conlin, Haeck, Neudecker, Parsons, White; Los Alamos National Laboratory technical report LA-UR-18-24034.