Tight Coupling: Improvements to UI

[albeanth]

This moves #1094 to here. TP and USNC have a joint interest in moving the development of the tight coupling user-interface forward. This discussion board serves to document 1) what we'd like to accomplish, 2) how we'd like to do it, and 3) the development tasks to accomplish the UI improvements.

---

Desired Outcomes

Moving parameters for convergence off of the interfaces and instead interact with the ARMI composites (via the database) directly. This new interface would look like

tightCouplingSettings:
    core:
        parameter: keff
        convergence: 1e-4
    blocks:
        parameter: power
        convergence: 1e-3

This would:

1. remove the ambiguity of parameters "belonging" to interfaces, since they really only "belong" to the ARMI data model.
2. be a cleaner/clearer approach to managing convergence on different composite levels (e.g., converging on assembly-power vs block power, peak assembly temperature vs block temperature, multiple temperatures [clad, fuel, coolant, etc], etc...)
3. (USNC request) To switch between relative and absolute convergence criteria or have both at the same time so we can move on when either one is met (like moose)

tightCouplingSettings:
    foo:
        parameter: bar
        # Stops iteration when either one is met
        abs_tolerance: 1e-4
        rel_tolerance: 1e-5 
   baz:
        parameter: qux
        abs_tolerance: 1e-4

5. (USNC request) More than one parameters per interface composite to evaluate the convergence

[albeanth]

Question 1

In the review of #1033, @john-science brought up concerns with adding additional functionality to the Operator class. Below are a few comments pulled from the review

• Add measure of convergence for tight coupling  #1033 (comment)
• Add measure of convergence for tight coupling  #1033 (comment)

So this begs the question, what would be the ideal approach?

@keckler had the idea of creating a new "TightCoupler" interface that sits on the end of the interface stack and is (presumably) active/executed if o.couplingIsActive() == True.

• Add measure of convergence for tight coupling  #1033 (comment)

@john-science also briefly mentioned/spit-balled the idea of an Operator subclass, ConvergenceOperator.

I think both ideas have their own pros and cons. What do we think would be ideal? Do folks have any other ideas to consider as well?

[albeanth]

Question 2

How do we want to define absolute and relative convergence? Should there be options exposed to the user?

• I imagine one might have an interest in switching between norms (inf-norm, 1-norm, 2-norm, etc).
• Currently, some parameters, like block-wise power, are normalized before their norms are measured. Do we want to enforce all params to be normalized in some manner? E.g., all block-wise parameters are normalized by some average or something and then a convergence is measured. For some parameters, like power, I would argue that it is necessary. Some discussion on this in Tight coupling: interpretability of convergence norms  #1093.

[albeanth]

Development Task 1

(USNC Request) Can we configure the behavior of ARMI after it failed to meet the convergence criteria after it exceeds the max number of iteration? We may want to fail immediately instead of moving on to the next node.

I think this is reasonable to do and would be a relatively easier task to do in the near-term. This would fit in here

armi/armi/operators/operator.py

Lines 416 to 420 in 26bda05

	if not converged:
	runLog.warning(
	f"Tight coupling iterations for c{cycle:02d}n{timeNode:02d} have not converged!"
	f" The maximum number of iterations, {self.cs[CONF_TIGHT_COUPLING_MAX_ITERS]}, was reached."
	)

We would need:

1. A new user setting to indicate if a run should fail on not converging
2. A conditional statement to throw a RuntimeError if that setting is turned on. Otherwise, issue the existing runLog.warning and continue forward.
3. A unit test to ensure that the RuntimeError gets hit.

@aalfonsi @slee-USNC @drewj-usnctech I think this could be a good task for USNC to take on if you're interested!

[aalfonsi]

@albeanth we can work on this. Thank you very much.