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 specifies an ORDER constant that specifies where in this order it should be placed in the Interface Stack.

Notes

Originally, the ordering was accomplished with a very large if/else construct in createInterfaces. This made more modular by moving the add/activate logic into each module and replacing the if/else with just a large hard-coded list of modules in order that could possibly be added. That hard-coded list presented ImportError problems when building various subset distributions of ARMI so this ordering mechanism was created to replace it, allowing the modules to define their required order internally.

Future improvements may include simply defining what information is required to perform a calculation and figuring out the ordering from that. It’s complex because in coupled simulations, everything depends on everything.

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 interactCoupled is called.

Parameters

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

• tolerance (float) – Defines the allowable error, epsilon, between the current previous parameter value(s) to determine if the selected coupling parameter has been converged.

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

storePreviousIterationValue()

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()

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 critera. 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 model and modules that operate upon it.

This defines the operator’s contract for interacting with the ARMI reactor model. It is expected that interact* methods are defined as appropriate for the physics modeling.

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: Optional[str] = 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.

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[Union[str, armi.settings.setting.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 CaseSettings 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 (CaseSettings) – 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)

Bases: object

A generic representation of a particular module’s output.

Variables

~OutputReader.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 (CaseSettings) – 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: armi.interfaces.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: armi.interfaces.Interface

Alias for field number 1

kwargs: dict

Alias for field number 2