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.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 = 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

_checkSettings()

Raises an exception if interface settings requirements are not met

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 master.

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.

_initializeParams()

Assign the parameters for active interfaces so that they will be in the database.

Notes

Parameters with defaults are not written to the database until they have been assigned SINCE_ANYTHING. This is done to reduce database size, so that we don’t write parameters to the DB that are related to interfaces that are not not active.

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 couping is active.

interactError()

Called if an error occurs.

interactDistributeState()

Called after this interface is copied to a different (non-master) 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)

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

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. Aboslute paths will not be copied anywhere.

The returned dictionary should be keyed off of a descriptive string, or an actual Setting object. If a Setting is used, then the source CaseSettings object will be updated to the new file location.

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.

success

False by default, set to True if the run is considered to have completed without error.

Type

bool

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

Bases: tuple

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)

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}

_field_types = {'interfaceCls': <class 'armi.interfaces.Interface'>, 'kwargs': <class 'dict'>, 'order': <class 'int'>}

_fields = ('order', 'interfaceCls', 'kwargs')

_fields_defaults = {}

classmethod _make(iterable)

Make a new InterfaceInfo object from a sequence or iterable

_replace(**kwds)

Return a new InterfaceInfo object replacing specified fields with new values

order

Alias for field number 0

interfaceCls

Alias for field number 1

kwargs

Alias for field number 2