armi.physics.executers module

Executors are useful for having a standard way to run physics calculations.

They may involve external codes (with inputs/execution/output) or in-memory data pathways.

class armi.physics.executers.ExecutionOptions(label=None)

Bases: object

A data structure representing all options needed for a physics kernel.

Implementation: Options for executing external calculations. I_ARMI_EX0

signature: ExecutionOptions requirements: R_ARMI_EX

Implements a basic container to hold and report options to be used in the execution of an external code (see I_ARMI_EX1). Options are stored as instance attributes and can be dumped as a string using describe(), which will include the name and value of all public attributes of the instance. Also facilitates the ability to execute parallel instances of a code by providing the ability to resolve a runDir that is aware of the executing MPI rank. This is done via setRunDirFromCaseTitle(), where the user passes in a caseTitle string, which is hashed and combined with the MPI rank to provide a unique directory name to be used by each parallel instance.

Variables:

• inputFile (str) – Name of main input file. Often passed to stdin of external code.

• outputFile (str) – Name of main output file. Often the stdout of external code.

• extraInputFiles (list of tuples) – (sourceName, destName) pairs of file names that will be brought from the working dir into the runDir. Allows renames while in transit.

• extraOutputFiles (list of tuples) – (sourceName, destName) pairs of file names that will be extracted from the runDir to the working dir

• executablePath (str) – Path to external executable to run (if external code is used)

• runDir (str) – Path on running system where the run will take place. This is often used to ensure external codes that use hard-drive disk space run on a local disk rather than a shared network drive

• workingDir (str) – Path on system where results will be placed after the run. This is often a shared network location. Auto-applied during execution by default.

• label (str) – A name for the run that may be used as a prefix for input/output files generated.

• interface (str) – A name for the interface calling the Executer that may be used to organize the input/output files generated within sub-folders under the working directory.

• savePhysicsFiles (bool) – Dump the physics kernel I/O files from the execution to a dedicated directory that will not be overwritten so they will be available after the run.

• copyOutput (bool) – Copy the output from running the executable back to the working directory.

• applyResultsToReactor (bool) – Update the in-memory reactor model with results upon completion. Set to False when information from a run is needed for auxiliary purposes rather than progressing the reactor model.

fromUserSettings(cs)

Set options from a particular Settings object.

fromReactor(reactor)

Set options from a particular reactor object.

resolveDerivedOptions()

Called by executers right before executing.

setRunDirFromCaseTitle(caseTitle: str) → None

Set run directory derived from case title and label.

This is optional (you can set runDir to whatever you want). If you use this, you will get a relatively consistent naming convention for your fast-path folders.

describe() → str

Make a string summary of all options.

class armi.physics.executers.Executer(options, reactor)

Bases: object

Short-lived object that coordinates a calculation step and updates a reactor.

Notes

This is deliberately not a MpiAction. Thus, Executers can run as potentially multiple steps in a parent (parallelizable ) MpiAction or in other flexible ways. This is intended to maximize reusability.

run()

Run the executer steps.

This should use the current state of the reactor as input, perform some kind of calculation, and update the reactor with the output.

class armi.physics.executers.DefaultExecuter(options, reactor)

Bases: Executer

An Executer that uses a common run sequence.

This sequence has been found to be relatively common in many externally-executed physics codes. It is here for convenience but is not required. The sequence look like:

• Choose modeling options (either from the global run settings input or dictated programmatically)

• Apply geometry transformations to the ARMI Reactor as needed

• Build run-specific working directory

• Write input file(s)

• Put specific input files and libs in run directory

• Run the analysis (external execution, or not)

• Process output while still in run directory

• Check error conditions

• Move desired output files back to main working directory

• Clean up run directory

• Un-apply geometry transformations as needed

• Update ARMI data model as desired

Implementation: Default tool for executing external calculations. I_ARMI_EX1

signature: DefaultExecuter requirements: R_ARMI_EX

Facilitates the execution of external calculations by accepting options (an ExecutionOptions object) and providing methods that build run directories and execute a code based on the values in options. The run() method will first resolve any derived options in the options object and check if the specified executablePath option is valid, raising an error if not. If it is, preparation work for executing the code is performed, such as performing any geometry transformations specified in subclasses or building the directories needed to save input and output files. Once the temporary working directory is created, the executer moves into it and runs the external code, applying any results from the run as specified in subclasses. Finally, any geometry perturbations that were performed are undone.

run()

Run the executer steps.

Warning

If a calculation requires anything different from what this method does, do not update this method with new complexity! Instead, simply make your own run sequence and/or class. This pattern is useful only in that it is fairly simple. By all means, do use DirectoryChanger and ExecuterOptions and other utilities.

writeInput()