Add measure of convergence for tight coupling

armi/bookkeeping/report/newReportUtils.py

@@ -294,7 +294,7 @@ def _setGeneralSimulationData(core, cs, coreDesignTable):
     coreDesignTable.addRow(["  ", ""])
     coreDesignTable.addRow(["Full Core Model", "{}".format(core.isFullCore)])
     coreDesignTable.addRow(
-        ["Loose Physics Coupling Enabled", "{}".format(bool(cs["looseCoupling"]))]
+        ["Tight Physics Coupling Enabled", "{}".format(bool(cs["tightCoupling"]))]
     )
     coreDesignTable.addRow(["Lattice Physics Enabled for", "{}".format(cs["genXS"])])
     coreDesignTable.addRow(

armi/bookkeeping/report/reportingUtils.py

@@ -765,8 +765,8 @@ def _setGeneralSimulationData(core, cs, coreDesignTable):
         "Full Core Model", "{}".format(core.isFullCore), coreDesignTable, report.DESIGN
     )
     report.setData(
-        "Loose Physics Coupling Enabled",
-        "{}".format(bool(cs["looseCoupling"])),
+        "Tight Physics Coupling Enabled",
+        "{}".format(bool(cs["tightCoupling"])),
         coreDesignTable,
         report.DESIGN,
     )

armi/interfaces.py

@@ -153,6 +153,11 @@ def __init__(self, r, cs):
         self.cs = settings.getMasterCs() if cs is None else cs
         self.r = r
         self.o = r.o if r else None
+        # default interface variables used for tight coupling
+        self.tightCouplingTolerance = 1e-4
+        self.tightCouplingVariables = None
+        self.tightCouplingConvergeOn = None
+        self.tightCouplingOldValue = None
 
     def __repr__(self):
         return "<Interface {0}>".format(self.name)
@@ -310,6 +315,10 @@ def interactCoupled(self, iteration):
         """Called repeatedly at each time node/subcycle when tight physics couping is active."""
         pass
 
+    def getTightCouplingValue(self):
+        """abstract method to retrive the value in which tight coupling is to converge on"""
+        pass
+
     def interactError(self):
         """Called if an error occurs."""
         pass

armi/operators/operator.py

@@ -30,6 +30,14 @@
 import re
 import shutil
 import time
+import collections
+from tabulate import tabulate
+from numpy.linalg import norm
+from numpy import (
+    subtract,
+    inf,
+    ndarray,
+)
 
 from armi import context
 from armi import interfaces
@@ -133,6 +141,7 @@ def __init__(self, cs):
         self._maxBurnSteps = None
         self._powerFractions = None
         self._availabilityFactors = None
+        self.convergenceSummary = None
 
         # Create the welcome headers for the case (case, input, machine, and some basic reactor information)
         reportingUtils.writeWelcomeHeaders(self, cs)
@@ -376,10 +385,16 @@ def _timeNodeLoop(self, cycle, timeNode):
         self.r.p.timeNode = timeNode
         self.interactAllEveryNode(cycle, timeNode)
         # perform tight coupling if requested
-        if self.cs["numCoupledIterations"]:
-            for coupledIteration in range(self.cs["numCoupledIterations"]):
+        if self.cs["tightCoupling"]:
+            self.convergenceSummary = collections.defaultdict(list)
+            for coupledIteration in range(self.cs["tightCouplingMaxNumIters"]):
                 self.r.core.p.coupledIteration = coupledIteration + 1
+                self._tightCouplingOldValues()
                 self.interactAllCoupled(coupledIteration)
+                converged = self._computeTightCouplingConvergence()
+                if converged:
+                    break
+            self._printTightCouplingReport()
             # database has not yet been written, so we need to write it.
             dbi = self.getInterface("database")
             dbi.writeDBEveryNode(cycle, timeNode)
@@ -618,6 +633,51 @@ def interactAllCoupled(self, coupledIteration):
         activeInterfaces = [ii for ii in self.interfaces if ii.enabled()]
         self._interactAll("Coupled", activeInterfaces, coupledIteration)
 
+    def _tightCouplingOldValues(self):
+        activeInterfaces = [ii for ii in self.interfaces if ii.enabled()]
+        for interface in activeInterfaces:
+            interface.tightCouplingOldValue = interface.getTightCouplingValue()
+
+    def _computeTightCouplingConvergence(self):
+        activeInterfaces = [ii for ii in self.interfaces if ii.enabled()]
+        convergence = []
+        for interface in activeInterfaces:
+            if interface.tightCouplingOldValue is not None:
+                key = interface.name+": "+interface.tightCouplingConvergeOn
+                if isinstance(interface.tightCouplingOldValue, float):
+                    eps = abs(interface.tightCouplingOldValue - interface.getTightCouplingValue())
+                elif isinstance(interface.tightCouplingOldValue, ndarray):
+                    newValue = interface.getTightCouplingValue()
+                    epsVec = []
+                    for old,new in zip(interface.tightCouplingOldValue, newValue):
+                        epsVec.append(norm(subtract(old,new), ord=2))
+                    eps = norm(epsVec, ord=inf)
+                else:
+                    raise RuntimeError("Only currently set up to handle either floats or lists... Sorry.")
+                self.convergenceSummary[key].append(eps)
+                if eps > interface.tightCouplingTolerance:
+                    convergence.append(False)
+                else:
+                    convergence.append(True)
+
+        self._printTightCouplingReport() # it's usually useful to print convergence progress as it unfolds
+        return all(convergence)
+
+    def _checkTightCouplingConvergence(self):
+        for interface,convergenceList in self.convergenceSummary.items():
+            for value in convergenceList:
+                if value > interface.tightCouplingTolerance:
+                    # one of the interfaces is not converged
+                    return False
+        # all interfaces are converged!
+        return True
+
+    def _printTightCouplingReport(self):
+        runLog.info("Tight Coupling Convergence Summary: Norm Type = Inf")
+        runLog.info(
+            tabulate(self.convergenceSummary, headers="keys", showindex=True, tablefmt="armi")
+        )
+
     def interactAllError(self):
         """Interact when an error is raised by any other interface. Provides a wrap-up option on the way to a crash."""
         for i in self.interfaces:
@@ -1063,4 +1123,4 @@ def setStateToDefault(cs):
 
     def couplingIsActive(self):
         """True if any kind of physics coupling is active."""
-        return self.cs["looseCoupling"] or self.cs["numCoupledIterations"] > 0
+        return self.cs["tightCoupling"]

armi/operators/settingsValidation.py

@@ -478,22 +478,11 @@ def _willBeCopiedFrom(fName):
         )
 
         self.addQuery(
-            lambda: not self.cs["looseCoupling"]
-            and self.cs["numCoupledIterations"] > 0,
-            "You have {0} coupled iterations selected, but have not activated loose coupling.".format(
-                self.cs["numCoupledIterations"]
-            ),
-            "Set looseCoupling to True?",
-            lambda: self._assignCS("looseCoupling", True),
-        )
-
-        self.addQuery(
-            lambda: self.cs["numCoupledIterations"] > 0,
-            "You have {0} coupling iterations selected.".format(
-                self.cs["numCoupledIterations"]
-            ),
-            "1 coupling iteration doubles run time (2 triples, etc). Do you want to use 0 instead? ",
-            lambda: self._assignCS("numCoupledIterations", 0),
+            lambda: (not self.cs["tightCoupling"] and self.cs["tightCouplingMaxNumIters"] != 15),
+            "You've requested a non default number of tight coupling iterations but left tightCoupling: False."
+            "Do you want to set tightCoupling to True?",
+            "",
+            lambda: self._assignCS("tightCoupling", True),
         )
 
         self.addQuery(

armi/physics/neutronics/globalFlux/globalFluxInterface.py

@@ -63,6 +63,9 @@ def __init__(self, r, cs):
         else:
             self.nodeFmt = "1d"  # produce ig001_1.inp.
         self._bocKeff = None  # for tracking rxSwing
+        # for tight coupling, overwrite base class
+        self.tightCouplingVariables = ["keff", "power"]
+        self.tightCouplingConvergeOn = "keff"
 
     @staticmethod
     def getHistoryParams():
@@ -222,6 +225,23 @@ def interactCoupled(self, iteration):
 
         GlobalFluxInterface.interactCoupled(self, iteration)
 
+    def getTightCouplingValue(self):
+        if self.tightCouplingConvergeOn == "keff":
+            return self.r.core.p.keff
+        if self.tightCouplingConvergeOn == "power":
+            scaledCorePowerDistribution = []
+            for a in self.r.core.getChildren():
+                scaledPower = []
+                assemPower = sum(b.p.power for b in a)
+                for b in a:
+                    scaledPower.append(b.p.power/assemPower)
+
+                scaledCorePowerDistribution.append(scaledPower)
+
+            return numpy.array(scaledCorePowerDistribution, dtype=object)
+
+        return None
+
     @staticmethod
     def getOptionsCls():
         """

armi/settings/fwSettings/globalSettings.py

@@ -77,7 +77,8 @@
 CONF_MODULE_VERBOSITY = "moduleVerbosity"
 CONF_MPI_TASKS_PER_NODE = "mpiTasksPerNode"
 CONF_N_CYCLES = "nCycles"
-CONF_NUM_COUPLED_ITERATIONS = "numCoupledIterations"
+CONF_TIGHT_COUPLING = "tightCoupling"
+CONF_TIGHT_COUPLING_MAX_ITERS = "tightCouplingMaxNumIters"
 CONF_OPERATOR_LOCATION = "operatorLocation"
 CONF_OUTPUT_FILE_EXTENSION = "outputFileExtension"
 CONF_PLOTS = "plots"
@@ -96,7 +97,6 @@
 CONF_FLUX_RECON = "fluxRecon"  # strange coupling in fuel handlers
 CONF_INDEPENDENT_VARIABLES = "independentVariables"
 CONF_HCF_CORETYPE = "HCFcoretype"
-CONF_LOOSE_COUPLING = "looseCoupling"
 CONF_T_IN = "Tin"
 CONF_T_OUT = "Tout"
 CONF_DEFERRED_INTERFACES_CYCLE = "deferredInterfacesCycle"
@@ -572,12 +572,16 @@ def defineSettings() -> List[setting.Setting]:
             description="Number of blocks with control for a REBUS poison search",
         ),
         setting.Setting(
-            CONF_NUM_COUPLED_ITERATIONS,
-            default=0,
-            label="Tight Coupling Iterations",
-            description="Number of tight coupled physics iterations to occur at each "
-            "timestep",
-            schema=vol.All(vol.Coerce(int), vol.Range(min=0)),
+            CONF_TIGHT_COUPLING,
+            default=False,
+            label="Tight Coupling",
+            description="Boolean to turn on/off tight coupling",
+        ),
+        setting.Setting(
+            CONF_TIGHT_COUPLING_MAX_ITERS,
+            default=15,
+            label="Maximum number of iterations for tight coupling.",
+            description="Maximum number of iterations for tight coupling."
         ),
         setting.Setting(
             CONF_OPERATOR_LOCATION,
@@ -719,14 +723,6 @@ def defineSettings() -> List[setting.Setting]:
             "on design being analyzed",
             options=["TWRC", "TWRP", "TWRC-HEX"],
         ),
-        setting.Setting(
-            CONF_LOOSE_COUPLING,
-            default=False,
-            label="Activate Loose Physics Coupling",
-            description="Update material densities and dimensions after running "
-            "thermal-hydraulics. Note: Thermal-hydraulics calculation is needed "
-            "to perform the loose physics coupling calculation.",
-        ),
         setting.Setting(
             CONF_T_IN,
             default=360.0,

armi/tests/armiRun.yaml

@@ -48,7 +48,6 @@ settings:
     armi.reactor.reactors: info
   nCycles: 6
   nodeGroup: OnlineNodes,TP
-  numCoupledIterations: 0
   outputFileExtension: png
   percentNaReduction: 10.0
   power: 100000000.0

armi/tests/detailedAxialExpansion/armiRun.yaml

@@ -37,7 +37,6 @@ settings:
   moduleVerbosity:
     armi.reactor.reactors: info
   nCycles: 6
-  numCoupledIterations: 0
   outputFileExtension: png
   power: 100000000.0
   shuffleLogic: ../refSmallReactorShuffleLogic.py

doc/user/assorted_guide.rst

@@ -1,5 +1,5 @@
 Physics Coupling
 ----------------
-Tight coupled physics can be activated though the ``numCoupledIterations``
+Tight coupled physics can be activated though the ``tightCoupling``
 setting. This is handled in the :py:meth:`mainOperate <armi.operators.Operator.mainOperate>`
 method.