armi.interfaces module

Interfaces are objects of code that interact with ARMI. They read information off the state, perform calculations (or run external codes), and then store the results back in the state.

Learn all about interfaces in Framework Architecture

See also

armi.operators

Schedule calls to various interfaces

armi.plugins

Register various interfaces

class armi.interfaces.STACK_ORDER

Bases: object

Constants that help determine the order of modules in the interface stack.

Each module defines an ORDER constant that specifies where in this order it should be placed in the Interface Stack.

Implementation: Define an ordered list of interfaces. I_ARMI_OPERATOR_INTERFACES0

signature: STACK_ORDER requirements: R_ARMI_OPERATOR_INTERFACES

At each time node during a simulation, an ordered collection of Interfaces are run (referred to as the interface stack). But ARMI does not force the order upon the analyst. Instead, each Interface registers where in that ordered list it belongs by giving itself an order number (which can be an integer or a decimal). This class defines a set of constants which can be imported and used by Interface developers to define that Interface’s position in the stack. The constants defined are given names, based on common stack orderings in the ARMI ecosystem. But in the end, these are just constant values, and the names they are given are merely suggestions.

See also

armi.operators.operator.Operator.createInterfaces, armi.physics.neutronics.globalFlux.globalFluxInterface.ORDER

BEFORE = -0.1

AFTER = 0.1

PREPROCESSING = 1.0

FUEL_MANAGEMENT = 2.0

DEPLETION = 3.0

FUEL_PERFORMANCE = 4.0

CROSS_SECTIONS = 5.0

CRITICAL_CONTROL = 6.0

FLUX = 7.0

THERMAL_HYDRAULICS = 8.0

REACTIVITY_COEFFS = 9.0

TRANSIENT = 10.0

BOOKKEEPING = 11.0

POSTPROCESSING = 12.0

class armi.interfaces.TightCoupler(param, tolerance, maxIters)

Bases: object

Data structure that defines tight coupling attributes that are implemented within an Interface and called upon when interactAllCoupled is called.

Implementation: The TightCoupler defines the convergence criteria for physics coupling. I_ARMI_OPERATOR_PHYSICS0

signature: TightCoupler requirements: R_ARMI_OPERATOR_PHYSICS

During a simulation, the developers of an ARMI application frequently want to iterate on some physical calculation until that calculation has converged to within some small tolerance. This is typically done to solve the nonlinear dependence of different physical properties of the reactor, like fuel performance. However, what parameter is being tightly coupled is configurable by the developer. This class provides a way to calculate if a single parameter has converged based on some convergence tolerance. The user provides the parameter, tolerance, and a maximum number of iterations to define a basic convergence calculation. If in the isConverged method the parameter has not converged, the number of iterations is incremented, and this class will wait, presuming another iteration is forthcoming.

Parameters:

• param (str) – The name of a parameter defined in the ARMI Reactor model.

• tolerance (float) – Defines the allowable error between the current and previous parameter values to determine if the selected coupling parameter has converged.

• maxIters (int) – Maximum number of tight coupling iterations allowed

storePreviousIterationValue(val: [<class 'float'>, <class 'int'>, <class 'list'>, <class 'numpy.ndarray'>])

Stores the previous iteration value of the given parameter.

Parameters:

val (_SUPPORTED_TYPES) – the value to store. Is commonly equal to interface.getTightCouplingValue()

Raises:

TypeError – Checks the type of the val against _SUPPORTED_TYPES before storing. If invalid, a TypeError is raised.

isConverged(val: [<class 'float'>, <class 'int'>, <class 'list'>, <class 'numpy.ndarray'>]) → bool

Return boolean indicating if the convergence criteria between the current and previous iteration values are met.

Parameters:

val (_SUPPORTED_TYPES) – The most recent value for computing convergence criteria. Is commonly equal to interface.getTightCouplingValue()

Returns:

True (False) interface is (not) converged

Return type:

boolean

Notes

• On convergence, this class is automatically reset to its initial condition to avoid retaining or holding a stale state. Calling this method will increment a counter that when exceeded will clear the state. A warning will be reported if the state is cleared prior to the convergence criteria being met.

• For computing convergence of arrays, only up to 2D is allowed. 3D arrays would arise from considering component level parameters. However, converging on component level parameters is not supported at this time.

Raises:

• ValueError – If the previous iteration value has not been assigned. The storePreviousIterationValue method must be called first.

• RuntimeError – Only support calculating norms for up to 2D arrays.

static getListDimension(listToCheck: list, dim: int = 1) → int

Return the dimension of a python list.

Parameters:

• listToCheck (list) – the supplied python list to have its dimension returned

• dim (int, optional) – the dimension of the list

Returns:

the dimension of the list. Typically 1, 2, or 3 but can be arbitrary order, N.

Return type:

dim, int

class armi.interfaces.Interface(r, cs)

Bases: object

The eponymous Interface between the ARMI reactor data model and the Plugins.

Implementation: The interface shall allow code execution at important operational points in time. I_ARMI_INTERFACE

signature: Interface requirements: R_ARMI_INTERFACE

The Interface class defines a number methods with names like interact***. These methods are called in order at each time node. This allows for an individual Plugin defining multiple interfaces to insert code at the start or end of a particular time node or cycle during reactor simulation. In this fashion, the Plugins and thus the Operator control when their code is run. The end goal of all this work is to allow the Plugins to carefully tune when and how they interact with the reactor data model. Interface instances are gathered into an interface stack in armi.operators.operator.Operator.createInterfaces().

Construct an interface.

The r and cs arguments are required, but may be None, where appropriate for the specific Interface implementation.

Parameters:

• r (Reactor) – A reactor to attach to

• cs (Settings) – Settings object to use

Raises:

RuntimeError – Interfaces derived from Interface must define their name

classmethod getDependencies(cs)

classmethod getInputFiles(cs)

Return a MergeableDict containing files that should be considered “input”.

name: str | None = None

The name of the interface. This is undefined for the base class, and must be overridden by any concrete class that extends this one.

function = None

The function performed by an Interface. This is not required be be defined by implementations of Interface, but is used to form categories of interfaces.

class Distribute

Bases: object

Enum-like return flag for behavior on interface broadcasting with MPI.

DUPLICATE = 1

NEW = 2

SKIP = 4

nameContains(name)

distributable()

Return true if this can be MPI broadcast.

Notes

Cases where this isn’t possible include the database interface, where the SQL driver cannot be distributed.

preDistributeState()

Prepare for distribute state by returning all non-distributable attributes.

Examples

>>> return {'neutronsPerFission',self.neutronsPerFission}

postDistributeState(toRestore)

Restore non-distributable attributes after a distributeState.

attachReactor(o, r)

Set this interfaces’ reactor to the reactor passed in and sets default settings.

Parameters:

• r (Reactor object) – The reactor to attach

• quiet (bool, optional) – If true, don’t print out the message while attaching

Notes

This runs on all worker nodes as well as the primary.

detachReactor()

Delete the callbacks to reactor or operator. Useful when pickling, MPI sending, etc. to save memory.

duplicate()

Duplicate this interface without duplicating some of the large attributes (like the entire reactor).

Makes a copy of interface with detached reactor/operator/settings so that it can be attached to an operator at a later point in time.

Returns:

The deepcopy of this interface with detached reactor/operator/settings

Return type:

Interface

getHistoryParams()

Add these params to the history tracker for designated assemblies.

The assembly will get a print out of these params vs. time at EOL.

getInterface(*args, **kwargs)

interactInit()

Interacts immediately after the interfaces are created.

Notes

BOL interactions on other interfaces will not have occurred here.

interactBOL()

Called at the Beginning-of-Life of a run, before any cycles start.

interactEOL()

Called at End-of-Life, after all cycles are complete.

interactBOC(cycle=None)

Called at the beginning of each cycle.

interactEOC(cycle=None)

Called at the end of each cycle.

interactEveryNode(cycle, node)

Called at each time node/subcycle of every cycle.

interactCoupled(iteration)

Called repeatedly at each time node/subcycle when tight physics coupling is active.

getTightCouplingValue()

Abstract method to retrieve the value in which tight coupling will converge on.

interactError()

Called if an error occurs.

interactDistributeState()

Called after this interface is copied to a different (non-primary) MPI node.

interactRestart(startNode: Tuple[int, int], previousNode: Tuple[int, int])

Perform any actions prior to simulating a restart.

Interfaces may want to restore some state that would have existed at the start of startNode prior to calling interactBOL() for the desired start point. The database interface will be used prior to any interfaces calling this method, so you can assume the reactor state has been correctly loaded from the database from the previousNode. This helps ensure that interfaces restart at e.g., (cycle, node)=(4, 3) would see the same data compared to the nominal simulation without a restart.

Parameters:

• startNode – Pair of (cycle, node) for the requested restart point.

• previousNode – Pair of (cycle, node) for the time node immediately preceeding startNode.

isRequestedDetailPoint(cycle=None, node=None)

Determine if this interface should interact at this reactor state (cycle/node).

Notes

By default, detail points are either during the requested snapshots, if any exist, or all cycles and nodes if none exist.

This is useful for peripheral interfaces (CR Worth, perturbation theory, transients) that may or may not be requested during a standard run.

If both cycle and node are None, this returns True

Parameters:

• cycle (int) – The cycle number (or None to only consider node)

• node (int) – The timenode (BOC, MOC, EOC, etc.).

Returns:

Whether or not this is a detail point.

Return type:

bool

workerOperate(_cmd)

Receive an MPI command and do MPI work on worker nodes.

Returns:

True if this interface handled the incoming command. False otherwise.

Return type:

bool

enabled(flag=None)

Mechanism to allow interfaces to be attached but not running at the interaction points.

Must be implemented on the individual interface level hooks. If given no arguments, returns status of enabled. If arguments, sets enabled to that flag. (True or False)

Notes

These return statements are inconsistent, but not wrong.

bolForce(flag=None)

Run interactBOL even if this interface is disabled.

Parameters:

flag (boolean, optional) – Will set the bolForce flag to this boolean

Returns:

true if should run at BOL. No return if you pass an input.

Return type:

bool

Notes

These return statements are inconsistent, but not wrong.

writeInput(inName)

Write input file(s).

readOutput(outName)

Read output file(s).

static specifyInputs(cs) → Dict[str | Setting, List[str]]

Return a collection of file names that are considered input files.

This is a static method (i.e. is not called on a particular instance of the class), since it should not require an Interface to actually be constructed. This would require constructing a reactor object, which is expensive.

The files returned by an implementation should be those that one would want copied to a target location when cloning a Case or CaseSuite. These can be absolute paths, relative paths, or glob patterns that will be interpolated relative to the input directory. Absolute paths will not be copied anywhere.

The returned dictionary will enable the source Settings object to be updated to the new file location. While the dictionary keys are recommended to be Setting objects, the name of the setting as a string, e.g., “shuffleLogic”, is still interpreted. If the string name does not point to a valid setting then this will lead to a failure.

Note

This existed before the advent of ARMI plugins. Perhaps it can be better served as a plugin hook. Potential future work.

See also

armi.cases.Case.clone

Parameters:

cs (Settings) – The case settings for a particular Case

updatePhysicsCouplingControl()

Adjusts physics coupling settings depending on current state of run.

class armi.interfaces.InputWriter(r=None, externalCodeInterface=None, cs=None)

Bases: object

Use to write input files of external codes.

getInterface(name)

Get another interface by name.

write(fName)

Write the input file.

class armi.interfaces.OutputReader(r=None, externalCodeInterface=None, fName=None, cs=None)

Bases: object

A generic representation of a particular module’s output.

Variables:

success (bool) – False by default, set to True if the run is considered to have completed without error.

Notes

Should ideally not require r, eci, and fname arguments and would rather just have an apply(reactor) method.

getInterface(name)

Get another interface by name.

read(fileName)

Read the output file.

apply(reactor)

Apply the output back to a reactor state.

This provides a generic interface for the output data of anything to be applied to a reactor state. The application could involve reading text or binary output or simply parameters to appropriate values in some other data structure.

armi.interfaces.getActiveInterfaceInfo(cs)

Return a list containing information for all of the Interface classes that are present.

This creates a list of tuples, each containing an Interface subclass and appropriate kwargs for adding them to an Operator stack, given case settings. There should be entries for all Interface classes that are returned from implementations of the describeInterfaces() function in modules present in the passed list of packages. The list is sorted by the ORDER specified by the module in which the specific Interfaces are described.

Parameters:

cs (Settings) – The case settings that activate relevant Interfaces

armi.interfaces.isInterfaceActive(klass, cs)

Return True if the Interface klass is active.

class armi.interfaces.InterfaceInfo(order: int, interfaceCls: Interface, kwargs: dict)

Bases: NamedTuple

Data structure with interface info.

Notes

If kwargs is an empty dictionary, defaults from armi.operators.operator.Operator.addInterface will be applied.

See also

armi.operators.operator.Operator.createInterfaces

where these ultimately activate various interfaces.

Create new instance of InterfaceInfo(order, interfaceCls, kwargs)

order: int

Alias for field number 0

interfaceCls: Interface

Alias for field number 1

kwargs: dict

Alias for field number 2