Handling isomers produced beyond (n,n*) reactions by eitan-weinstein · Pull Request #229 · svalinn/ALARA

eitan-weinstein · 2026-01-20T16:27:11Z

This PR expands on the isomer handling methods for ALARAJOYWrapper developed over the past month to properly address isomer daughters produced from pathways other than (n,n*) reactions. I came across this issue when doing inventory benchmarking against FISPACT-II and the JAEA FNS experimental data and noticed certain isomers appearing to be stable when they obviously were not, just like before. The old method failed to include cases where the parent itself is an isomer, which can subsequently produce excited daughters by normal reaction pathways.

gonuke

a few questions and comments

gonuke · 2026-01-25T18:36:45Z

tools/ALARAJOYWrapper/tendl_processing.py

    """

-    return M == 0
+    return M == 0 and dKZA % 10 == 0


should we have set M correctly before this in these circumstances?

The way that we define M in reaction_data.py determines if a daughter is left in an excited state by specific emitted particle tags from the MT string formatting. However, that formatting does not account for cases where the parent is already excited, meaning the del_KZA value would calculate an excited daughter as well. M is generally parent-ambivalent, so I think I'll need to do a parent-by-parent recalculation of M at the start of the MT for loop to account for excited parents.

gonuke · 2026-01-25T18:39:33Z

tools/ALARAJOYWrapper/tendl_processing.py

-            _is_ground_state_nuc(rxn['isomer']) or
-            _is_isomer_with_decay_data(dKZA, radionucs, rxn['isomer'])
+            _is_ground_state_daughter(rxn['isomer'], dKZA) or
+            _is_isomer_with_decay_data(dKZA, pKZA, radionucs, rxn['isomer'])


do we care if its an isomer anymore? given this or we only care that it has decay data, right?

I don't think we can only go decay data because then we would be excluding all stable nuclides from the standard processing and directing them incorrectly to the special isomer handling in the else block.

But all stable nuclides are in the ground state, so they should be handled by the first condition.

I guess my point is, we've already captured all the ground state nuclides in the first condition, so we know that any nuclides we are testing must be an isomer

Ok, I agree with what you are saying about stable nuclides all being handled by the first condition, but I'm not sure I understand what change you are requesting.

_is_isomer_with_decay_data can just be refactored to be _has_decay_data and doesn't need to check if it's an isomer

gonuke · 2026-01-25T18:43:21Z

tools/ALARAJOYWrapper/tendl_processing.py

        else:
            if to_ground:
-                decay_KZA = f'{pKZA // 10}*'
+                div_KZA = pKZA if rxn['emitted'] == 'n' else dKZA


cant we always use dkza? for an emitted neutron, I assume pkza == dkza

Yes, I think you're right. Although, after closer inspection, I realized the assignment of decay_KZA was reversed, based on the actual meaning of the to_ground Boolean, which I'll have updated in the next commit.

gonuke · 2026-01-28T12:46:04Z

tools/ALARAJOYWrapper/tendl_processing.py

    return sigma_list[::-1]

-def _is_ground_state_nuc(M):
+def _is_ground_state_daughter(M):


I don't this it's correct to name this about daughters. You are only passing in M which could theoretically come from anywhere. The fact that you may only use it for daughters should not affect its name.

gonuke · 2026-01-28T12:50:26Z

tools/ALARAJOYWrapper/tendl_processing.py

-            _is_ground_state_nuc(rxn['isomer']) or
-            _is_isomer_with_decay_data(dKZA, radionucs, rxn['isomer'])
+            _is_ground_state_daughter(rxn['isomer'], dKZA) or
+            _is_isomer_with_decay_data(dKZA, pKZA, radionucs, rxn['isomer'])


But all stable nuclides are in the ground state, so they should be handled by the first condition.

I guess my point is, we've already captured all the ground state nuclides in the first condition, so we know that any nuclides we are testing must be an isomer

gonuke

continued cleanup of the isomer checking

gonuke · 2026-02-04T15:27:14Z

tools/ALARAJOYWrapper/tendl_processing.py

    """

-    return dKZA in radionucs and M in range(1,10)
+    return dKZA in radionucs and ((pKZA % 10) + M in range(1,10))


do we still need to test the isomeric state of the parent?

In principle, yes, although I don't know if we'd ever actually run into a case where this would come up, which would be having a parent whose excitation level is 10 and somehow still has decay data. This is obviously very unlikely to happen, given that I don't think there is decay data beyond any M=2, but technically this covers a physical case that could exist.

But didn't we just decide that this method only cares whether there is decay data or not?

This is called in one place: to decide whether we keep the cross-section as-is or collapse it. It seems to me that we should keep all cross-sections where the daughter is ground state (you have a function for that) or where the daughter has decay data (this function). It shouldn't matter whether it's an isomer or not.

Maybe I'm not defining the function clearly enough, but I think the problem that I am trying to address here is that the KZA arithmetic allows for the production of daughters that could appear to have decay data, but only as a result of the limitations of the KZA convention, not because the actual daughter produced is represented in the radionucs dictionary. The simplest example of this would an (n,n10) reaction of a ground state parent, like what I have in the _has_decay_data() docstring: ⁶Li(n,n10) -> ^6,m10Li + n, but in KZA notation it would be 30060 + n10 -> 300610 + n. The problem here is that the KZA of the daughter does correspond to a nuclide with decay data, just not the correct daughter because 300610 = ⁶¹Zn. Perhaps my implementation is not capturing this accurately, but what I am trying to capture the parameters of the problem of not allowing any double digit excited states because the isomeric properties inescapably affect the legitimacy of a KZA value, and by extension our ability to use that KZA to cross-reference the decay data.

I think we should be creating some clear metadata about these cases sooner then, perhaps? As soon as we determine what the daughter KZA is, we should also set some metadata to capture this.

eitan-weinstein · 2026-02-05T17:40:25Z

tools/ALARAJOYWrapper/tendl_processing.py

        else:
            if to_ground:
-                decay_KZA = f'{pKZA // 10}*'
+                decay_KZA = (dKZA // 10 - rxn['isomer'] // 10) * 10


I realized that the version of this formula that I had in previous commits for this PR was incorrect.

Previously it was:

decay_KZA = (dKZA // 10) * 10

When benchmarking the FNS data, I was noticing a number of non-physical reaction pathways represented (specifically it was ⁵¹V(n,n*)->⁵³V which caught my attention as being obviously incorrect). I realized that the reason for this was that for double digit excited states, this rounding-down to 10 method would not account for the dKZA already being corrupted by the unallowed KZA operation with a double-digit M. Therefore, I changed it to:

decay_KZA = (dKZA // 10 - rxn['isomer'] // 10) * 10

to bring the tens-digit back to appropriate value after any isomeric corruption may occur (unaffected by any M < 10)

gonuke

The suggestion we discussed today

tools/ALARAJOYWrapper/tendl_processing.py

gonuke

Can you provide a handful of examples of the kinds of reactions that need the special treatment of the isomer data? It seems like we keep ratcheting up the value of or isomeric information.

gonuke · 2026-02-10T12:54:01Z

tools/ALARAJOYWrapper/tendl_processing.py

+        if parent_excitation > 0 and MT not in EXCITATION_REACTIONS:
+            M += parent_excitation


This surprises me a little - that we're adding the parent excitation to the isomeric state that we already had in the MT table? Or does this only occur when rxn['isomer'] == 0?

gonuke · 2026-02-10T12:54:31Z

tools/ALARAJOYWrapper/tendl_processing.py

+
+    # Force isomeric daughters with high excitation levels or without known
+    # half-lives to their ground state, and flag the change
+    if pKZA % 10 + M >= 10 or dKZA not in radionucs:


Below, we've already added the parent excitation to M and it seems like we do it again here?

eitan-weinstein · 2026-02-10T20:00:20Z

Per my Thread in the Slack channel, I think on top of figuring out whether isomeric parents' reaction residuals default to the ground state or the equivalent isomeric state, I also think that I need to recalibrate the forced-ground accumulation in general, because I think that I was overlooking that MTs 4 and 103-107 were already accumulated, so to calculate just the ground state, I would have to subtract from the accumulated isomeric cross-sections instead.

…action basis

…tically to ground.

gonuke

The cognitive burden of our processing of these excitation reactions is getting hard to follow. I've requested that we pull some parts out into separate functions to make it clearer.

gonuke · 2026-03-03T13:03:39Z

tools/ALARAJOYWrapper/tendl_processing.py

+        if MT in excitation_pathways[pKZA]:
+            return excitation_pathways[pKZA][MT], excitation_pathways
+        else:
+            return 0, excitation_pathways


(Magic number)
Let's define a variable

default_state = 0

And return that instead of just returning 0 so that we can easily change it later.

gonuke · 2026-03-03T13:06:57Z

tools/ALARAJOYWrapper/tendl_processing.py

+    # Parse File 10 for allowed daughter excitations from a given reaction
+    excitation_pathways[pKZA] = {}
+
+    za = f'{(pKZA // 10) * 10 + delKZA}'[:-1]


I need to be reminded (again?) when we every produce pKZA values that need this treatment...

I suppose that we sometimes have a parent nuclide in an isomeric state and we want to block that isomeric state when we apply the MT-specific change in KZA. This is particularly true given recent discussion of not assuming that reaction products are in the same isomeric state as their parents.

gonuke · 2026-03-03T13:08:01Z

tools/ALARAJOYWrapper/tendl_processing.py

+    for line in section.content.split('\n'):
+        if za in line:
+            excitation_levels.append(int(
+                line.split(za)[1].strip().split(' ')[0]


Can we add a comment somewhere with the format of the line we are parsing here? This is compact/concise, but a little obtuse.

gonuke · 2026-03-03T13:12:54Z

tools/ALARAJOYWrapper/tendl_processing.py

+            # Reset deLKZA for (n,n*) excitation reactions
+            if delKZA >= 0 and MT in EXCITATION_REACTIONS:


The EXCITATION_REACTIONS are no longer just (n,n*) so don't some of them still have a non-zero delKZA?

gonuke · 2026-03-03T13:16:42Z

tools/ALARAJOYWrapper/tendl_processing.py

+    return excitation_pathways[pKZA][MT], excitation_pathways

-def iterate_MTs(MTs, file_obj, mt_dict, pKZA, all_rxns, radionucs, to_ground):
+def iterate_MTs(MTs, file_obj, mt_dict, pKZA, all_rxns, eaf_nucs, endf_path):


I think it will lower cognitive burden if we break some of the code in this method into different functions.

Originally, the purpose of this function was just to iterate through the data and extract simple cross-sections for writing to the final file.

Now we do a lot of cleanup and cross-checking. It would be great if those steps were done in their own functions to make the overall flow of this method more clear and isolate where we perform those operations.

We might end up passing around a lot of data (which makes me feel like we should probably think about making this object oriented some day but not now).

gonuke requested changes Jan 25, 2026

View reviewed changes

gonuke requested changes Jan 28, 2026

View reviewed changes

gonuke requested changes Feb 4, 2026

View reviewed changes

eitan-weinstein commented Feb 5, 2026

View reviewed changes

gonuke requested changes Feb 7, 2026

View reviewed changes

tools/ALARAJOYWrapper/tendl_processing.py Show resolved Hide resolved

gonuke reviewed Feb 10, 2026

View reviewed changes

Excluding effectively elastic scattering

be89c83

eitan-weinstein mentioned this pull request Feb 11, 2026

Excluding "effectively elastic" neutron scattering reactions #243

Merged

Eitan Shai Weinstein and others added 16 commits February 11, 2026 12:29

Non-n isomer reactions

e41fe02

Fixing ground state collapse

7b51116

Responding to requested changes and fixing parent M value on a per-re…

b580e50

…action basis

Removing outdated argument

1db7ff5

Changing to function name to _is_ground_state()

25c6997

Changing to _has_decay_data()

fd20e8f

Responding to requested changes and fixing forced grounding formula

a1b1991

Docstring fix

6255c31

Fixing M accumulation bug

c9e2dd1

Changing dKZA processing, conditionals

247614a

Simplifying conditionals by removing outdated single-use function

b62d23b

Using MF10 to cross-check daughter excitation

1a72423

Responding to requested changes and fixing parent M value on a per-re…

16505ed

…action basis

Docstring fix

ce8b880

Fixing M accumulation bug

3dd746e

Simplifying conditionals by removing outdated single-use function

34d6595

eitan-weinstein force-pushed the non_n_isomer_rxns branch from 46c3585 to 34d6595 Compare February 13, 2026 21:46

Eitan Shai Weinstein and others added 4 commits February 13, 2026 15:47

finishing rebase

2a53316

No longer need to specifically track 'isomer' in mt_dict

910cb7d

Fixing double M accumulation

57953cf

Returning single-digit M condition

0d74044

Eitan Shai Weinstein and others added 4 commits February 16, 2026 10:05

Removing obsolete printout

adcf5ba

Fixing MT for (n,2n) rxns

59bf35b

Removing unnecessary print statement

3f3b442

Iteratively deexciting high-isomers level-by-level, instead of automa…

a7f3331

…tically to ground.

eitan-weinstein mentioned this pull request Feb 18, 2026

Improve physical robustness of ALARAJOY isomer handling #244

Open

Ensuring no double-digit M's in new deexcitation method

2a1a993

eitan-weinstein requested a review from gonuke February 19, 2026 21:22

gonuke requested changes Mar 3, 2026

View reviewed changes

		if parent_excitation > 0 and MT not in EXCITATION_REACTIONS:
		M += parent_excitation

		# Reset deLKZA for (n,n*) excitation reactions
		if delKZA >= 0 and MT in EXCITATION_REACTIONS:

Conversation

eitan-weinstein commented Jan 20, 2026

Uh oh!

gonuke left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gonuke left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eitan-weinstein Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gonuke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gonuke left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eitan-weinstein commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gonuke left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

eitan-weinstein Feb 5, 2026 •

edited

Loading

eitan-weinstein commented Feb 10, 2026 •

edited

Loading