NJOY interoperability

IRMA writes standard ENDF-6 MF7 tapes carrying the thermal scattering law S(α,β), so the files it produces are meant to flow straight into NJOY's processing chain. This page shows how to push an IRMA MF7 tape through RECONR / BROADR / THERMR / ACER, documents the two stock-NJOY THERMR defects that matter for coherent inelastic_mode = 2 tapes and how to patch them, and describes thermr_mimic, the offline validation tool that compares two S(α,β) tables without launching a full NJOY job, along with the cases where only a real THERMR run will do.

Processing an IRMA tape with NJOY

IRMA produces the MF7 evaluation; NJOY turns it into broadened, self-shielded, ACE-format thermal data. The usual module order is:

Module	Role for a thermal scattering evaluation
RECONR	Reconstruct the pointwise cross sections for the principal scatterer's neutron sublibrary and write a clean PENDF (pointwise-ENDF) tape.
BROADR	Doppler-broaden those cross sections to the evaluation temperature.
THERMR	Read IRMA's MF7 (MT2 coherent/incoherent elastic, MT4 inelastic), reconstruct the secondary energy–angle distributions, and add the thermal cross sections to the PENDF tape.
ACER	Format the result as an ACE-format thermal file for transport codes such as MCNP.

THERMR is the module that actually processes the tabulated S(α,β), so it is where the two patches below matter.

A minimal processing run

The stream below is the one the validation record ran for the nickel evaluations (RECONR, BROADR, THERMR at 299.15 K); adapt the four material-specific values for your own tape. NJOY reads its input on stdin and exchanges data through numbered files named tape<NN>: here tape20 is the IRMA thermal tape, tape21 the base neutron evaluation for the same nuclide (here Ni-58), tape23 the broadened pointwise file, and tape31 the thermal output.

reconr
21 22 /
'pendf for Ni' /
2825 1 /              -- the base evaluation's MAT number
0.001 /               -- reconstruction tolerance
'Ni58 base' /
0 /
broadr
21 22 23 /
2825 1 /
0.001 /
299.15 /              -- the evaluation temperature of the IRMA tape
0 /
thermr
20 23 31 /
59 2825 32 1 2 1 0 1 250 1 /   -- 59 = the IRMA tape's MAT, 2825 = the base MAT,
                               -- 32 angle bins, 1 temperature, iinc=2 (read S(a,b)),
                               -- icoh=1 (elastic from tape), natom=1, MT250 output
299.15 /
0.001 5.0 /           -- tolerance and maximum energy [eV]
stop

Run it with the njoy executable's working directory holding the tapes (njoy < input). For an ACE file for Monte Carlo codes, an acer module follows the same pattern; the NJOY manual documents its cards. The quickstart's graphite tape processes the same way with its own MAT (30), a carbon base evaluation, and 296 K.

One unit convention trips people up when reading results back: NJOY refers to its numbered I/O files as tapes, and its tape34-style cross-section output reports incident neutron energies in MeV, not eV, while the input file and IRMA's own grids work in eV or units of kT. Keep the conversion in mind when you compare a processed inelastic cross section against an IRMA-internal curve.

Stock NJOY2016 THERMR corrupts coherent mode-2 tapes (`cliq` defect)

A coherent inelastic_mode = 2 tape (graphite and other strongly coherent crystals) run through an unpatched NJOY2016 THERMR produces either ~1e91-barn nonsense in the inelastic cross section above roughly 0.27 eV, or a multi-hour stall, regardless of how the beta grid is spaced. The bug is in stock thermr.f90, not in the IRMA tape: THERMR trips on the shape of a coherent S(α,β), so emitting a uniform energy grid does not cure it. A correct tape is no protection here; apply the one-line two-axis guard fix below before trusting a coherent mode-2 tape through NJOY. Most materials, and all inelastic_mode = 0/1 tapes, are unaffected.

Mechanism

THERMR has a small-α liquid extrapolation it uses below the table's first α point (forward scattering, μ → 1):

s = sab(1,1) + log(alpha(1)/a)/2 - cliq*b**2/a
cliq = (sab(1,1) - sab(1,2)) * alpha(1) / beta(2)**2

In thermr.f90's notation sab(iα, iβ) is the tabulated S(α,β), α-index first. The activation guard tests for decay along alpha only:

if (sab(1,1).gt.sab(2,1)) then       ! cited at two sites in thermr.f90

but the cliq formula's sign requires decay along beta as well. A coherent mode-2 S(α,β) has a β = 0 row that decays in α (acoustic intensity concentrated in the first low-Q bin) yet rises in β at α₁. That drives cliq negative, so -cliq*b**2/a becomes +|cliq|*b²/a and exp(+|cliq|*b²/a) grows to about 1e150 or overflows to Inf: the ~1e91-barn values in tape34. Liquids satisfy both decays, which is why upstream never saw it.

Symptom table

Tape	Stock NJOY2016 THERMR	After the two-axis patch
`inelastic_mode = 0` (classic)	clean	clean (byte-identical)
`inelastic_mode = 1` (incoherent approx.)	clean	clean (byte-identical)
`inelastic_mode = 2`, weakly coherent	usually clean	clean
`inelastic_mode = 2`, strongly coherent (e.g. graphite)	~`1e91` b above ~`0.27 eV`, or a multi-hour stall	clean (and the patch is regression-clean: a mode-1 tape34 is byte-identical before and after it)

The one-line two-axis guard fix

Require decay along both axes at each cliq activation site in src/thermr.f90:

! before
if (sab(1,1).gt.sab(2,1)) then
! after
if (sab(1,1).gt.sab(2,1).and.sab(1,1).gt.sab(1,2)) then

Apply it at both cliq activation sites in calcem (thermr.f90:1964 and 2286; sig() only uses cliq), then rebuild NJOY. The patch is regression-clean: an inelastic_mode = 0/1 tape34 is byte-identical before and after, and a patched THERMR processes a coherent mode-2 graphite tape (auto grid included) straight through to a sane cross section. The defect is reported upstream, with a synthetic reproducer, as njoy/NJOY2016#399.

A uniform β grid does not avoid the defect; with the patched THERMR, use the standard automatic grid.

Transfers that fall beyond the tabulated S(α,β) are handled downstream by THERMR's short-collision-time (SCT) extension, driven by the tape's effective temperature (a spectrum-weighted temperature written on the tape for exactly this purpose); you do not need to extend the IRMA grid to cover them.

THERMR ignores the MF7/MT4 interpolation flag (lin-lin tapes)

The second defect is quieter. THERMR reads the MF7/MT4 interpolation flag but does not honor lin-lin (INT=2) interpolation through the path that reconstructs the inelastic cross section; everything is treated as log-lin there. Reported upstream as njoy/NJOY2016#410, with the patch attached. For sharp coherent mode-2 tapes written with IRMA's iint option this matters: log-lin interpolation floors the deep coherent near-zeros of the table and biases the cross section near the inelastic minimum low (for graphite, lin-lin processing raises the minimum by about 9% at 296 K and about 6% at 500 K; the two schemes converge on a sufficiently dense grid). The validation record therefore uses a second local THERMR patch that selects the interpolation rule from the tape; it leaves processing of log-lin tapes byte-identical. Smooth incoherent mode-0/1 tables have no such near-zeros, and log-lin remains adequate for them.

Neither the cliq fix nor the interpolation fix is part of the released NJOY2016 distribution; the corrected THERMR built from both patches is what the validation record means by "corrected NJOY THERMR".

Known deliberate divergences from NJOY's LEAPR

IRMA reproduces fresh NJOY2016.78 tapes exactly and the published ENDF/B-VIII.1 tapes to below 7e-5 on the golden set under tests/, but the NJOY behaviors below are handled differently on purpose: bugs, placeholders, or numerical hazards in NJOY itself that IRMA does not reproduce. Each is marked with an "NJOY divergence" comment at the code site, except the bfact guard, which never changes a physical result. The list is a maintainer-level record: the variable and routine names follow NJOY's own source, and each entry names its consequence for users.

Discrete-oscillator delta lines (twt = 0 input files). NJOY's discre reuses its idone flag for both the line loop and the inner grid-search (leapr.f90:1549-1585), so it adds only the first in-range negative delta line and then stops. IRMA convolves every in-range line, the physically complete treatment. Consequence: a twt = 0 input file with discrete oscillators (Einstein-solid hydrides and similar) will not match an NJOY tape at the delta-line betas; expect large local ratios there. Input files with twt > 0 (all the validation-set input files) never enter this path and remain byte-faithful.
iel = 5 (lead) coherent elastic. NJOY ships pb4 = 1.0 barn (a placeholder, not the physical sigma_coh(Pb) = 11.115 b), so NJOY iel=5 tapes carry a coherent-elastic component ~11.1x too small. IRMA uses the physical constant (irma/core/crystal.py). An IRMA Pb tape therefore deliberately disagrees with NJOY's by that factor.
SCT effective temperature accumulated across the α grid (discre). NJOY initializes the short-collision-time effective-temperature ratio once before the α loop (leapr.f90:1401) and adds the oscillator contributions for every α without ever resetting it (leapr.f90:1494), so its T_eff/T grows linearly with the α index: in a two-oscillator probe, by the last α of a 40-point grid the SCT tails change support entirely (313 of 512 tape lines differ, by up to 100% on tail values), and merely adding α points changes the answer. That is a latent NJOY bug: T_eff/T is a property of the phonon spectrum, not of the grid position. IRMA resets the ratio for every α. Affects only SCT tails reached through discrete oscillators; the validation-set input files have no SCT-tail exposure and match NJOY (to below 7e-5) either way.
ln-S sentinel for zero-S points (ENDF writer). NJOY's endout writes the ln-S sentinel −999 in the first-temperature TAB1 and the isym=1/2/3 LIST branches, but writes 0 in the isym=0 additional-temperature LIST branch (leapr.f90:3482). THERMR stores ilog values verbatim as ln S (thermr.f90:1754), so NJOY's 0 sentinel resurrects those zero-S points as S = e⁰ = 1 downstream, a demonstrable NJOY bug. IRMA writes −999 at every temperature, which keeps S ≈ 0 (safely below THERMR's sabflg = −225 floor). Affects the additional-temperature blocks of isym=0, log-stored tapes.
Print-flag-dependent SCT start index (phonon expansion). The monotonicity clamp on the SCT start index sits inside if (iprint.ne.0) in NJOY (leapr.f90:566-571), so NJOY's physics output depends on the print flag. IRMA applies the clamp unconditionally. All NJOY reference tapes in the expected set were generated with iprint ≠ 0 (clamp active), and IRMA reproduces them to below 7e-5; an iprint=0 NJOY run can differ where the SCT range begins.
Translational self-term clamp (trans). NJOY clamps only the convolution part of the translational S(α,β) (leapr.f90:940) and writes any self-term sum down to smin = 1e-75 via endout. IRMA re-clamps the combined convolution-plus-self term below 1e-30, so a self term landing in (1e-75, 1e-30), reached only at high α where the Debye-Waller weight α·f0 ≳ 70, is zeroed where NJOY keeps it. All validation-set input files reproduce their NJOY references to below 7e-5 with the clamp active.
Overflow guard in the discrete-oscillator Bessel factors (bfact). IRMA leaves a term at zero when its exponential argument exceeds 709, because Python's math.exp raises there; NJOY's Fortran would give Inf. The case is not reached for physical input files: the Bessel coefficient of such a term has already fallen below 1e-30, and both codes then skip the term, so the outputs agree.
SCT prefactor square root (sint). The SCT tail evaluated when a discrete-oscillator or rotational shift pushes |β| past the tabulated range is a Gaussian, normalized by the square root of 4π·wt·α·T̄ like every sibling SCT/free-gas expression in the module. NJOY divides by 4π·wt·α·T̄ itself (leapr.f90:1892), which is wrong unless that product happens to be 1. IRMA uses the square root. It affects only the SCT tail reached from discre and coldh; the validation-set input files and the NJOY minitapes do not reach it and stay byte-identical. Both implementations (sint_vec, _sint_batch_exact) carry it.
Coherent-elastic edge thinning at later temperatures (ENDF writer). NJOY's endout drops the Bragg edges that no longer change the running cumulative S at the first temperature, and each later temperature's LIST block then adds the last kept edge's contribution once for every dropped edge. While no edge contributes noticeably more at a later temperature, IRMA writes exactly NJOY's table. When some edge does (a stiffer Card 11-12 or Card 12e spectrum given for that temperature), NJOY's later blocks come out far too large; IRMA then keeps the edges that temperature needs and adds each edge's own contribution once.

Four have been reported upstream: njoy/NJOY2016#402 (discre delta lines), njoy/NJOY2016#403 (lead pb4) and njoy/NJOY2016#413 (the SCT square root and the accumulated SCT effective temperature).

How the validation record compared S(α,β) tables (`thermr_mimic`)

thermr_mimic is the validation record's own reimplementation of THERMR's tabulated-S(α, β) inelastic-cross-section kernel. It is not part of the irma package or this repository. The validation record used it to compare two S(α, β) tables (for example an IRMA mode-2 table and one derived from OCLIMAX) at the inelastic-cross-section level without a full NJOY job. On the finest grid both programs can process, it agrees with corrected NJOY THERMR to a median of 0.05% and at worst 0.8% (see the validation methodology).

It does not reproduce the short-collision-time extrapolation beyond the tabulated grid, the full secondary energy–angle reconstruction, or the ACE-format output; those comparisons used real THERMR. A table converted from an external code (for example an OCLIMAX S(Q, E) map) can agree with the mimic yet diverge in real THERMR through the short-collision-time extrapolation, so for the THERMR runs such tables were first rebuilt, either uniformly resampled or composited into a full evaluation whose grid THERMR handles.

THERMR `calcem` cosine-clamping warnings

When THERMR's calcem routine reconstructs angular distributions it can emit warnings about clamping scattering cosines back into the physical [-1, 1] range. In the validation runs these messages did not indicate a defect in the tape; they come from the adaptive reconstruction at grid edges. If they appear together with other failed checks, investigate.