2. Inputs

ARMI input files define the initial state of the reactor model and tell ARMI what kind of analysis should be performed on it.

Note

We have a Building input files for a fast reactor tutorial for a quick overview of the inputs.

There are several input files:

Settings file

Contains simulation parameters (like full power, cycle length, and which physics modules to activate) and all kind of modeling approximation settings (e.g. convergence criteria)

Blueprints file

Contains dimensions and composition of the components/blocks/assemblies in your reactor systems, from fuel pins to heat exchangers

Fuel management file

Describes how fuel moves around during a simulation

Depending on the type of analysis, developers may create other input files for things like: control logic, ex-core models for transients and shielding, etc.

2.1. YAML Files

ARMI’s input files all use the YAML format. This is a well- known file format, chosen because it is human-readable and easy to hand-write. That being said, there are two details about the YAML format that are important to know:

Ordering

YAML is not order specific; however, one of the techniques used to limit the size of the input includes using YAML anchors to resuse block and component definitions. YAML anchors (e.g. &block_name) must be defined before their corresponding alias (e.g. *block_name) used.

Duplicate Keys

YAML allows for duplicate keys. However, in ARMI, duplicates might be erroneous. Unfortunately, because the international YAML specification allows for duplicates, none of the YAML-parsing libraries see it as an error. You will have to hand-verify your inputs are correct.

2.2. The Settings Input File

The settings input file defines a series of key/value pairs the define various information about the system you are modeling as well as which modules to run and various modeling/approximation settings. For example, it includes:

  • The case title

  • The reactor power

  • The number of cycles to run

  • Which physics solvers to activate

  • Whether or not to perform a critical control search

  • Whether or not to do tight coupling iterations

  • What neutronics approximations specific to the chosen physics solver to apply

  • Environment settings (paths to external codes)

  • How many CPUs to use on a computer cluster

This file is a YAML file that you can edit manually with a text editor or with the ARMI GUI.

Here is an excerpt from a settings file:

  beta: 0.003454
  BOL: true
  branchVerbosity: debug
  buGroups:
    - 100
  burnSteps: 2
  clusterExclusive: false
  comment: Simple test input.
  crossSectionControl:
    DA:
      geometry: 0D
      blockRepresentation: Median
      criticalBuckling: true

A full listing of settings available in the framework may be found in the Table of all global settings .

Many settings are provided by the ARMI Framework, and others are defined by various plugins.

2.2.1. The ARMI GUI

The ARMI GUI may be used to manipulate many common settings (though the GUI can’t change all of the settings). The GUI also enables the graphical manipulation of a reactor core map, and convenient automation of commands required to submit to a cluster. The GUI is a front-end to these files. You can choose to use the GUI or not, ARMI doesn’t know or care — it just reads these files and runs them.

Note that one settings input file is required for each ARMI case, though many ARMI cases can refer to the same Blueprints, Core Map, and Fuel Management inputs.

Tip

The ARMI GUI is not yet included in the open-source ARMI framework

2.2.1.1. The assembly clicker

The assembly clicker (in the grids editor) allows users to define the 2-D layout of the assemblies defined in the The Blueprints Input File. This can be done in hexagon or cartesian. The results of this arrangement get written to grids in blueprints. Click on the assembly palette on the right and click on the locations where you want to put the assembly. By default, the input assumes a 1/3 core model, but you can create a full core model through the menu.

If you want one assembly type to fill all positions in a ring, right click it once it is placed and choose Make ring like this hex. Once you submit the job or save the settings file (File -> Save), you will be prompted for a new name of the geometry file before the settings file is saved. The geometry setting in the main tab will also be updated.

2.2.1.2. The ARMI Environment Tab

The environment tab contains important settings about which version of ARMI you will run and with which version of Python, etc. Most important is the ARMI location setting. This points to the codebase that will run. If you want to run the released version of ARMI, ensure that it is set in this setting. If you want to run a developer version, then be sure to update this setting.

Other settings on this tab may need to be updated depending on your computational environment. Talk to your system admins to determine which settings are best.

2.2.2. Some special settings

A few settings warrant additional discussion.

2.2.2.1. Detail assemblies

Many plugins perform more detailed analysis on certain regions of the reactor. Since the analyses often take longer, ARMI has a feature, called detail assemblies to help. Different plugins may treat detail assemblies differently, so it’s important to read the plugin documentation as well. For example, a depletion plugin may perform pin-level depletion and rotation analysis only on the detail assemblies. Or perhaps CFD thermal/hydraulics will be run on detail assemblies, while subchannel T/H is run on the others.

Detail assemblies are specified by the user in a variety of ways, through the GUI or the settings system.

Warning

The Detail Assemblies mechanism has begun to be too broad of a brush for serious multiphysics calculations with each plugin treating them differently. It is likely that this feature will be extended to be more flexible and less surprising in the future.

Detail Assembly Locations BOL

The detailAssemLocationsBOL setting is a list of assembly location strings (e.g. 004-003 for ring 4, position 3). Assemblies that are in these locations at the beginning-of-life will be activated as detail assemblies.

Detail assembly numbers

The detailAssemNums setting is a list of assemNums that can be inferred from a previous case and specified, regardless of when the assemblies enter the core. This is useful for activating detailed treatment of assemblies that enter the core at a later cycle.

Detail all assemblies

The detailAllAssems setting makes all assemblies in the problem detail assemblies

2.2.2.2. Kinetics settings

In reactor physics analyses it is standard practice to represent reactivity in either absolute units (i.e., dk/kk’ or pcm) or in dollars or cents. To support this functionality, the framework supplies the beta and decayConstants settings to apply the delayed neutron fraction and precursor decay constants to the Core parameters during initialization.

These settings come with a few caveats:

  1. The beta setting supports two different meanings depending on the type that is provided. If a single value is given, then this setting is interpreted as the effective delayed neutron fraction for the system. If a list of values is provided, then this setting is interpreted as the group-wise (precursor family) delayed neutron fractions (useful for reactor kinetics simulations).

  2. The decayConstants setting is used to define the precursor decay constants for each group. When set, it must be provided with a corresponding beta setting that has the same number of groups. For example, if six-group delayed neutron fractions are provided, the decay constants must also be provided in the same six-group structure.

  3. If beta is interpreted as the effective delayed neutron fraction for the system, then the decayConstants setting will not be utilized.

  4. If both the group-wise beta and decayConstants are provided and their number of groups are consistent, then the effective delayed neutron fraction for the system is calculated as the summation of the group-wise delayed neutron fractions.

2.2.2.3. Cycle history

For all cases, nCycles and power must be specified by the user. In the case that only a single state is to be examined (i.e. no burnup), the user need only additionally specify nCycles = 1.

In the case of burnup, the reactor cycle history may be specified using either the simple or detailed option. The simple cycle history consists of the following case settings:

  • power

  • nCycles (default = 1)

  • burnSteps (default = 4)

  • availabilityFactor(s) (default = 1.0)

  • cycleLength(s) (default = 365.2425)

In addition, one may optionally use the powerFractions setting to change the reactor power between each cycle. With these settings, a user can define a history in which each cycle may vary in power, length, and uptime. The history is restricted, however, to each cycle having a constant power, to each cycle having the same number of burnup nodes, and to those burnup nodes being evenly spaced within each cycle. An example simple cycle history might look like

power: 1000000
nCycles: 3
burnSteps: 2
cycleLengths: [100, R2]
powerFractions: [1.0, 0.5, 1.0]
availabilityFactors: [0.9, 0.3, 0.93]

Note the use of the special shorthand list notation, where repeated values in a list can be specified using an “R” followed by the number of times the value is to be repeated.

The above scheme would represent 3 cycles of operation:

  1. 100% power for 90 days, split into two segments of 45 days each, followed by 10 days shutdown (i.e. 90% capacity)

  2. 50% power for 30 days, split into two segments of 15 days each, followed by 70 days shutdown (i.e. 15% capacity)

  3. 100% power for 93 days, split into two segments of 46.5 days each, followed by 7 days shutdown (i.e. 93% capacity)

In each cycle, criticality calculations will be performed at 3 nodes evenly-spaced through the uptime portion of the cycle (i.e. availabilityFactor``*``powerFraction), without option for changing node spacing or frequency. This input format can be useful for quick scoping and certain types of real analyses, but clearly has its limitations.

To overcome these limitations, the detailed cycle history, consisting of the cycles setting may be specified instead. For each cycle, an entry to the cycles list is made with the following optional fields:

  • name

  • power fractions

  • cumulative days, step days, or burn steps + cycle length

  • availability factor

An example detailed cycle history employing all of these fields could look like

power: 1000000
nCycles: 4
cycles:
  - name: A
    step days: [1, 1, 98]
    power fractions: [0.1, 0.2, 1]
    availability factor: 0.1
  - name: B
    cumulative days: [2, 72, 78, 86]
    power fractions: [0.2, 1.0, 0.95, 0.93]
  - name: C
    step days: [5, R5]
    power fractions: [1, R5]
  - cycle length: 100
    burn steps: 2
    availability factor: 0.9

Note that repeated values in a list may be again be entered using the shorthand notation for step days, power fractions, and availability factors (though not cumulative days because entries must be monotonically increasing).

Such a scheme would define the following cycles:

  1. A 2 day power ramp followed by full power operations for 98 days, with three nodes clustered during the ramp and another at the end of the cycle, followed by 900 days of shutdown

  2. A 2 day power ramp followed by a prolonged period at full power and then a slight power reduction for the last 14 days in the cycle

  3. Constant full-power operation for 30 days split into six even increments

  4. Constant full-power operation for 90 days, split into two equal-length 45 day segments, followed by 10 days of downtime

As can be seen, the detailed cycle history option provides much greated flexibility for simulating realistic operations, particularly power ramps or scenarios that call for unevenly spaced burnup nodes, such as xenon buildup in the early period of thermal reactor operations.

Note

Although the detailed cycle history option allows for powers to change within each cycle, it should be noted that the power over each step is still considered to be constant.

Note

The name field of the detailed cycle history is not yet used for anything, but this information will still be accessible on the operator during runtime.

Note

Cycles without names will be given the name None

Warning

When a detailed cycle history is combined with tight coupling, a subclass of LatticePhysicsInterface.interactCoupled should be used.

2.2.2.4. Restart cases

Oftentimes the user is interested in re-examining just a specific set of time nodes from an existing run. In these cases, it is sometimes not necessary to rerun an entire reactor history, and one may instead use one of the following options:

  1. Snapshot, where the reactor state is loaded from a database and just a single time node is run.

  2. Restart, where the cycle history is loaded from a database and the calculation continues through the remaining specified time history.

For either of these options, it is possible to alter the specific settings applied to the run by simply adjusting the case settings for the run. For instance, a run that originally had only neutronics may incorporate thermal hydraulics during a snapshot run by adding in the relevant TH settings.

Note

For either of these options, it is advisable to first create a new case settings file with a name different than the one from which you will be restarting off of, so as to not overwrite those results.

To run a snapshot, the following settings must be added to your case settings:

  • Set runType to Snapshots

  • Add a list of cycle/node pairs corresponding to the desired snapshots to dumpSnapshot formatted as 'CCCNNN'

  • Set reloadDBName to the existing database file that you would like to load the reactor state from

An example of a snapshot run input:

runType: Snapshots
reloadDBName: my-old-results.h5
dumpSnapshot: ['000000', '001002'] # would produce 2 snapshots, at BOL and at node 2 of cycle 1

To run a restart, the following settings must be added to your case settings:

  • Set runType to Standard

  • Set loadStyle to fromDB

  • Set startCycle and startNode to the cycle/node that you would like to continue the calculation from (inclusive). startNode may use negative indexing.

  • Set reloadDBName to the existing database file from which you would like to load the reactor history up to the restart point

  • If you would like to change the specified reactor history (see Restart cases), keep the history up to the restarting cycle/node unchanged, and just alter the history after that point. This means that the cycle history specified in your restart run should include all cycles/nodes up to the end of the simulation. For complicated restarts, it may be necessary to use the detailed cycles setting, even if the original case only used the simple history option.

A few examples of restart cases:

  • Restarting a calculation at a specific cycle/node and continuing for the remainder of the originally-specified cycle history:
    # old settings
    nCycles: 2
    burnSteps: 2
    cycleLengths: [100, 100]
    runType: Standard
    loadStyle: fromInput
    loadingFile: my-blueprints.yaml
    
    # restart settings
    nCycles: 2
    burnSteps: 2
    cycleLengths: [100, 100]
    runType: Standard
    loadStyle: fromDB
    startCycle: 1
    startNode: 0
    reloadDBName: my-original-results.h5
    
  • Add an additional cycle to the end of a case:
    # old settings
    nCycles: 1
    burnSteps: 2
    cycleLengths: [100]
    runType: Standard
    loadStyle: fromInput
    loadingFile: my-blueprints.yaml
    
    # restart settings
    nCycles: 2
    burnSteps: 2
    cycleLengths: [100, 100]
    runType: Standard
    loadStyle: fromDB
    startCycle: 0
    startNode: -1
    reloadDBName: my-original-results.h5
    
  • Restart but cut the reactor history short:
    # old settings
    nCycles: 3
    burnSteps: 2
    cycleLengths: [100, 100, 100]
    runType: Standard
    loadStyle: fromInput
    loadingFile: my-blueprints.yaml
    
    # restart settings
    nCycles: 2
    burnSteps: 2
    cycleLengths: [100, 100]
    runType: Standard
    loadStyle: fromDB
    startCycle: 1
    startNode: 0
    reloadDBName: my-original-results.h5
    
  • Restart with a different number of steps in the third cycle using the detailed cycles setting:
    # old settings
    nCycles: 3
    burnSteps: 2
    cycleLengths: [100, 100, 100]
    runType: Standard
    loadStyle: fromInput
    loadingFile: my-blueprints.yaml
    
    # restart settings
    nCycles: 3
    cycles:
      - cycle length: 100
        burn steps: 2
      - cycle length: 100
        burn steps: 2
      - cycle length: 100
        burn steps: 4
    runType: Standard
    loadStyle: fromDB
    startCycle: 2
    startNode: 0
    reloadDBName: my-original-results.h5
    

Note

The skipCycles setting is related to skipping the lattice physics calculation specifically, it is not required to do a restart run.

Note

The X-SHUFFLES.txt file is required to do explicit repeated fuel management.

Note

The restart.dat file is required to repeat the exact fuel management methods during a branch search. These can potentially modify the reactor state in ways that cannot be captures with the SHUFFLES.txt file.

Note

The ISO binary cross section libraries are required to run cases that skip the lattice physics calculation (e.g. MC^2)

Note

The multigroup flux is not yet stored on the output databases. If you need to do a restart with these values (e.g. for depletion), then you need to reload from neutronics outputs.

Note

Restarting a calculation with an different version of ARMI than what was used to produce the restarting database may result in undefined behavior.

2.3. The Blueprints Input File

The blueprints input defines the dimensions of structures in the reactor, as well as their material makeup. In a typical case, pin dimensions, isotopic composition, control definitions, coolant type, etc. are defined here. The specifics of each assembly type are then overlayed, possibly including enrichment distributions and other material modifications.

Note

See the blueprints module for implementation and more detail.

This input file is formatted using YAML, which allows text-based change tracking for design control. ARMI does not have a blueprints-editing GUI yet, but may in the future.

Note

You can point many ARMI runs to the same Blueprints input file using full paths in loadingFile setting.

ARMI adds an !include YAML tag, which can be used to include the contents of an external YAML file in any part of a blueprints file. The can be useful for sharing core or assembly pin layouts amongst multiple cases. For example:

grids:
    core: !include path/to/core_grid.yaml

would have the effect of copy-pasting the contents of path/to/core_grid.yaml into the main blueprints file. The rules that ARMI uses to handle things like indentation of the included text are usually rather intuitive, but sometimes it can be useful to witness the behavior first-hand. The expand-bp command can be used to do a dry run for testing inputs with !includes.

ARMI models are built hierarchically, first by defining components, and then by larger and larger collections of the levels of the reactor.

2.3.1. Blueprint sections

The blueprints input file has several sections that corresponds to different levels of the reactor hierarchy. You will generally build inputs “bottoms up”, first by defining elementary pieces (like pins) and then collecting them into the core and reactor.

The ARMI data model is represented schematically below, and the blueprints are defined accordingly:

../_images/armi_reactor_objects.png

The primary data containers in ARMI

blocks:

Defines Component inputs for a Block.

assemblies:

Defines vertical stacks of blocks used to define the axial profile of an Assembly.

systems:

Reactor-level structures like the core, the spent fuel pool, pumps, the head, etc.

grids:

Lattice definitions for the core map or pin maps

nuclide flags:

Special setting: Specifies nuclide modeling options, whether a nuclide is being modeled for cross sections and/or depletion. For instance, it allows you to ignore nuclides above Curium for depletion speed. This also allows you to expand elements to a subset of nuclides. For example, you can choose to expand Oxygen to just Oxygen-16 and neglect Oxygen-17 and 18.

custom isotopics:

Special setting: defines user-specified isotopic compositions.

The core map input files can be graphically manipulated with the Grid editor.

2.3.2. Blocks and Components

Blocks and components are defined together in the blueprints input.

We will start with a component, and then define the whole blocks: input. The structure will be something like:

blocks:
    block name 1:
        component name 1:
            ...
        component name 2:
    block name 2:
        component name 1:
            ...
        component name 2:
            ...

Note

You can also define components at the top level of the blueprints file under the components: top level section, but bringing anything defined there into the reactor model must currently be done programatically. We are currently developing additional input capabilities to use these more flexibly.

Associated with this is a component groups: section which can collect different free components with different volume fractions. This also is not fully implemented yet.

2.3.2.1. Defining a Component

The Components section defines the pin (if modeling a pin-type reactor) and assembly in-plane dimensions (axial dimensions are defined in the Assemblies input) and the material makeups of each Component. Blocks are defined here as collections of geometric components that have specific temperatures, dimensions, material properties, and isotopic compositions.

An component may be defined as:

fuel:
    shape: Circle
    material: UZr
    Tinput: 20.0
    Thot: 450.0
    mult: 169
    id: 0.0
    od: 0.757

Here we have provided the following information:

Component name

The component name (fuel) is specified at the top. Some physics kernels interpret names specially, so pay attention to any naming conventions. As a general rule, you can expect that people will be doing regex on your name, so you should not use any of these characters in your component names: . ^ $ * + ? { } [ ] \ | ( ) :.

shape

The shape will be extruded to the length specified in the assemblies input section below. ARMI contains a variety of built-in simple shapes, and plugins can define their own design-specific/proprietary shapes.

material

The material links the component to a certain set of thermo-physical properties (e.g. temperature-dependent thermal expansion coefficients, density, thermal conductivity, etc., which are used in the various physics kernels. Natural isotopic composition is determined from this material specification as well (unless custom isotopics are supplied). The entry here should either be a class name of a valid material (UZr) or a module:className pair for specifying specific material (e.g. armi.materials.uZr:UZr). Materials are handled through the material library.

Tinput

The temperature (in C) that corresponds to the input dimensions given here. This facilitates automatic thermal expansion.

Thot

The temperature (in C) that the component dimensions will be thermal expanded to (using material properties based on the material input). To disable automatic thermal expansion, set Tinput and Thot both to the same value

mult

Multiplicity specifies how many duplicates of this component exist in this block. If you want 169 pins per assembly, this would be 169. This does not explicitly describe the location of the pins. Note that many fast-neutron systems only need volume fractions, not precise spatial locations, at least for pre-conceptual/simple studies.

id

Inner diameter (in cm). Each shape has different required input dimension keys. For annulus, set id to non-zero.

od

Outer diameter (in cm).

2.3.2.2. Component Types

Each component has a variety of dimensions to define the shape and composition. All dimensions are in cm. The following is a list of included component shapes and their dimension inputs. Again, additional/custom components with arbitrary dimensions may be provided by the user via plugins.

Component Name

Dimensions

Component

ShapedComponent

Circle

od, id, mult, modArea

Hexagon

op, ip, mult, modArea

Rectangle

lengthOuter, lengthInner, widthOuter, widthInner, mult, modArea

SolidRectangle

lengthOuter, widthOuter, mult, modArea

Square

widthOuter, widthInner, mult, modArea

Triangle

base, height, mult, modArea

HoledHexagon

op, holeOD, nHoles, mult, modArea

HexHoledCircle

od, holeOP, mult, modArea

HoledRectangle

holeOD, lengthOuter, widthOuter, mult, modArea

HoledSquare

holeOD, widthOuter, mult, modArea

Helix

od, axialPitch, helixDiameter, mult, id, modArea

Sphere

od, id, mult, modArea

Cube

lengthOuter, lengthInner, widthOuter, widthInner, heightOuter, heightInner, mult, modArea

RadialSegment

inner_radius, outer_radius, height, mult, inner_theta, outer_theta

DifferentialRadialSegment

inner_radius, radius_differential, inner_axial, height, inner_theta, azimuthal_differential, mult

NullComponent

UnshapedComponent

modArea

UnshapedVolumetricComponent

op, volume

ZeroMassComponent

op, volume

PositiveOrNegativeVolumeComponent

op, volume

DerivedShape

modArea

When a DerivedShape is specified as the final component in a block, its area is inferred from the difference between the area of the block and the sum of the areas comprised by the other components in the block. This is useful for complex shapes like coolant surrounding a lattice of pins.

2.3.2.4. Pin lattices

Pin lattices may be explicitly defined in the block/component input in conjunction with the grids input section. A block may assigned a grid name, and then each component may be assigned one or more grid specifiers.

For example, the following input section specifies that fuel pins will occupy all grid positions marked with a 1 and cladding components will occupy all grid positions marked with either a 1 or a 2. This situation may be desirable when some burnable poison pins use the same cladding as the fuel pins.

blocks:
    fuel: &block_fuel
        grid name: fuelgrid
        fuel:
            flags: fuel test
            shape: Circle
            material: UZr
            Tinput: 25.0
            Thot: 600.0
            id: 0.0
            mult: 169.0
            od: 0.86602
            latticeIDs: [1]
        clad:
            shape: Circle
            material: HT9
            Tinput: 25.0
            Thot: 470.0
            id: 1.0
            mult: fuel.mult
            od: 1.09
            latticeIDs: [1,2]

Note

A grid with the name fuelgrid must be defined as well in the grid input section.

2.3.3. Flags and naming

All objects in the ARMI Reactor Model possess a set of armi.reactor.flags.Flags, which can be used to affect the way that the various physics kernels treat each object. Most flags are named after common reactor components, like FUEL, or CLAD, and are used to declare what something is in the reactor model. Various physics or other framework operations can then be parameterized to target specific types of things. For instance, the fuel handling code can infer that blocks with the GRID_PLATE flag should be considered stationary and not move them with the rest of the block stack in an assembly.

Historically, flags have also been used to describe directly what should be done with an object in the reactor model. For instance, an object with the DEPLETABLE flag set will participate in isotopic depletion analysis, whereas objects without the DEPLETION flag set will not. This has led to a lot of confusion, as the meaning of various flags is buried deep within the code, and can conflict from place to place. We are trying to align around a what something is interpretation, and bind those to specific behaviors with settings. For more details, see armi.reactor.flags.

The set of specific flags that should be set on an object can be specified in one of two ways for each object defined in the blueprints. The most precise way is to use include a flags: entry for the object blueprint in question. In the example above, the fuel component sets the FUEL and TEST flags. When specifying flags in this way, the value specified must be completely and unambiguously convertible into valid Flags. If it cannot, it will lead to an error when constructing the object.

If flags: is empty, or not specified, then the name of the object blueprint will be used to infer as many flags as possible. In the above example, the clad component will get the CLAD flag from its name.

Note

Additional flags may be specified from plugins, but this should be done with care; see the armi.reactor.flags module and armi.plugins.ArmiPlugin.defineFlags() plugin hook for more details.

2.3.4. Assemblies

Once components and blocks are defined, Assemblies can be created as extruded stacks of blocks from bottom to top. The assemblies use YAML anchors to refer to the blocks defined in the previous section.

Note

We aren’t happy with the use of anchors to refer to blocks, and plan to change it (back) to just using the block names directly. However, the use of anchors for input to be applied to multiple assemblies (e.g. heights) is quite nice.

A complete definition of an inner-core assembly may be seen below:

assemblies:
    heights: &standard_heights [10.05, 20.10, 30.15, 20.10, 20.10, 30.15]
    axial mesh points: &standard_axial_mesh_points [1, 2, 3, 4, 5, 6]
    inner core:
        specifier: IC
        blocks: &inner_core_blocks [*block_shield, *block_fuel, *block_fuel, *block_fuel, *block_fuel, *block_plenum]
        height: *standard_heights
        axial mesh points: *standard_axial_mesh_points
        hotChannelFactors: TWRPclad
        material modifications:
            U235_wt_frac: ['', '', 0.001, 0.002, 0.03, '']
            ZR_wt_frac: ['', '', 0.1, 0.1, 0.1, 0.1]
        nozzleType: Inner
        xs types: [A, B, C, D, E, F]

Note

While component dimensions are entered as cold dimensions, axial heights may be entered as either cold or hot dimensions. In older versions of ARMI, it was required to enter heights in the hot dimension (this behavior is preserved by setting inputHeightsConsideredHot: True). However, with the axial expansion changer, heights may be entered at cold temperatures (inputHeightsConsideredHot: False). Each Assembly will then be expanded to its hot dimensions upon construction.

For many cases, a shared height and axial mesh point definition is sufficient. These can be included globally as shown above and linked with anchors, or specified explicitly.

specifier

The Geometry Assembly Specifier, which is a two-letter ID, such as “IC” (for inner core), “SH” (for shield), etc. correspond with labels in the geometry input file that is created by the GUI hex dragger.

xs types

The cross-section type is usually a single capital letter that identifies which cross section (XS) set will be applied to the block. Each cross section set must be defined for at least one block with fissile fuel. When the lattice physics code executes in ARMI, it determines the representative blocks from each cross section type and burnup group and runs it to create the cross section set for all blocks of the same type and in the same burnup group. Generally, it is best to set blocks that have much different compositions to have separate cross section types. The tradeoff is that the more XS types you define, the more CPU time the case will take to run.

Representing xsType by a single letter (A-Z) or number (0-9) limits users to 36 groups. So ARMI will allow 2-letter xsType designations if and only if the buGroups setting has length 1 (i.e. no burnup groups are defined). This is useful for high-fidelity XS modeling.

axial mesh points

Blocks will be broken up into this many uniform mesh points in the deterministic neutronics solvers (e.g. DIF3D). This allows you to define large blocks that have multiple flux points within them. You have to keep the neutronic mesh somewhat uniform in order to maintain numerical stability of the solvers. It is important to note that the axial mesh must be uniform throughout the core for many physics kernels, so be sure all block interfaces are consistent among all assemblies in the core. Blocks deplete and get most state variables on the block mesh defined by the height specification. Provisions for multiple meshes for different physics are being planned.

hotChannelFactors

A label to define which set of hot channel factors (HCFs) get applied to this block in the thermal/hydraulic calculations. There are various valid sets included with ARMI.

nozzleType

This is a string that identifies what type of inlet nozzle an assembly has. This parameter could be used in an implementation of a thermal-hydraulics solver with flow orificing to apply different pressure loss coefficients and/or flow rates to different types of assemblies.

material modifications

These are a variety of modifications that are made to the materials in blocks in these locations. It may include the fuel enrichment (mass frac.), poison enrichment (mass frac.), zirconium mass frac, and any additional options required to fully define the material loaded in the component. The material definitions in the material library define valid modifications for them.

Material Name

Available Modifications

B4C

B10_wt_frac, theoretical_density, TD_frac

FuelMaterial

class1_custom_isotopics, class2_custom_isotopics, class1_wt_frac, customIsotopics

Lithium

LI_wt_frac, LI6_wt_frac

Sulfur

sulfur_density_frac, TD_frac

ThU

U233_wt_frac, class1_custom_isotopics, class2_custom_isotopics, class1_wt_frac, customIsotopics

Thorium

class1_custom_isotopics, class2_custom_isotopics, class1_wt_frac, customIsotopics, class1_custom_isotopics, class2_custom_isotopics, class1_wt_frac, customIsotopics

ThoriumOxide

TD_frac, class1_custom_isotopics, class1_wt_frac, class2_custom_isotopics, customIsotopics

UThZr

U235_wt_frac, ZR_wt_frac, class1_custom_isotopics, class2_custom_isotopics, class1_wt_frac, customIsotopics

UZr

U235_wt_frac, ZR_wt_frac, class1_custom_isotopics, class2_custom_isotopics, class1_wt_frac, customIsotopics

Uranium

U235_wt_frac, TD_frac, class1_custom_isotopics, class2_custom_isotopics, class1_wt_frac, customIsotopics

UraniumOxide

TD_frac, U235_wt_frac, class1_custom_isotopics, class1_wt_frac, class2_custom_isotopics, customIsotopics

The class 1/class 2 modifications in fuel materials are used to identify mixtures of custom isotopics labels for input scenarios where a varying blend of a high-reactivity feed with a low-reactivity feed. This is often useful for closed fuel cycles. For example, you can define any fuel material as being made of LWR-derived TRU plus depleted uranium at various weight fractions. Note that this input style only adjusts the heavy metal.

To enable the application of different values for the same material modification type on different components within a block, the user may specify material modifications by component. This is useful, for instance, when two pins within an assembly made of the same base material have different fuel enrichments. This is done using the by component attribute to the material modifications as in:

blocks:
    fuel: &block_fuel
        fuel1: &component_fuel_fuel1
            shape: Hexagon
            material: UZr
            Tinput: 600.0
            Thot: 600.0
            ip: 0.0
            mult: 1
            op: 10.0
        fuel2: &component_fuel_fuel2
            shape: Hexagon
            material: UZr
            Tinput: 600.0
            Thot: 600.0
            ip: 0.0
            mult: 1
            op: 10.0
assemblies:
    fuel a: &assembly_a
        specifier: IC
        blocks: [*block_fuel]
        height: [1.0]
        axial mesh points: [1]
        xs types: [A]
        material modifications:
            by component:
                fuel1:
                    U235_wt_frac: [0.20]
                fuel2:
                    Zr_wt_frac: [0.02]
            U235_wt_frac: [0.30]

Material modifications specified on the material modifications level are referred to as “block default” values and apply to all components on the block not associated with a by-component value. This example would apply an enrichment of 20% to the fuel1 component and an enrichment of 30% to all other components in the block that accept the U235_wt_frac material modification.

All by-component material modifications override any block default material modifications of the same type. In addition, any by-component entries omitted for a given axial block will revert to the block default (or material class default, if no block default value is provided and a material class default exists) value:

blocks:
    fuel: &block_fuel
        fuel1: &component_fuel_fuel1
            shape: Hexagon
            material: UZr
            Tinput: 600.0
            Thot: 600.0
            ip: 0.0
            mult: 1
            op: 10.0
        fuel2: &component_fuel_fuel2
            shape: Hexagon
            material: UZr
            Tinput: 600.0
            Thot: 600.0
            ip: 0.0
            mult: 1
            op: 10.0
assemblies:
    fuel a: &assembly_a
        specifier: IC
        blocks: [*block_fuel, *block_fuel]
        height: [0.5, 0.5]
        axial mesh points: [1, 1]
        xs types: [A, A]
        material modifications:
            by component:
                fuel1:
                    U235_wt_frac: [0.20, ''] # <-- the U235_wt_frac for the second block will go to the block defaul value
                fuel2: # the U235_wt_frac for fuel2 component in both axial blocks will go to the block default values
                    Zr_wt_frac: [0.02, ''] # <-- the Zr_wt_frac for the second block will go to the material class default because there is no block default value
            U235_wt_frac: [0.30, 0.30]

The first block listed is defined at the bottom of the core. This is typically a grid plate or some other structure.

2.3.5. Systems

Once assemblies are defined they can be grouped together into the Core, the spent fuel pool (SFP), etc.

A complete reactor structure with a core and a SFP may be seen below:

systems:
    core:
        grid name: core
        origin:
            x: 0.0
            y: 10.1
            z: 1.1
    Spent Fuel Pool:
        type: sfp
        grid name: sfp
        origin:
            x: 1000.0
            y: 12.1
            z: 1.1

The origin defines the point of origin in global space in units of cm. This allows you to define the relative position of the various structures. The grid name inputs are string mappings to the grid definitions described below.

2.3.5.1. Plugin Behavior

The armi.plugins.ArmiPlugin.defineSystemBuilders() method can be provided by plugins to control how ARMI converts the systems section into Composites to be modeled. By default, the type field is used to determine what object is created. The default armi.reactor.ReactorPlugin provides the following mapping:

type Value

Builds

core (default)

Core

sfp

SpentFuelPool

Plugins are able to provide a superset (e.g., include core and sfp) and new mappings of values to builders.

2.3.6. Grids

Grids are described inside a blueprint file using lattice map or grid contents fields to define arrangements in Hex, Cartesian, or R-Z-Theta. The optional lattice pitch entry allows you to specify spacing between objects that is different from tight packing. This input is required in mixed geometry cases, for example if Hexagonal assemblies are to be loaded into a Cartesian arrangement. The contents of a grid may defined using one of the following:

lattice map:

A ASCII map representing the grid contents

grid contents:

a direct YAML representation of the contents

Example grid definitions are shown below:

grids:
    control:
        geom: hex
        symmetry: full
        lattice map: |
           - - - - - - - - - 1 1 1 1 1 1 1 1 1 4
            - - - - - - - - 1 1 1 1 1 1 1 1 1 1 1
             - - - - - - - 1 8 1 1 1 1 1 1 1 1 1 1
              - - - - - - 1 1 1 1 1 1 1 1 1 1 1 1 1
               - - - - - 1 1 1 1 1 1 1 1 1 1 1 1 1 1
                - - - - 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
                 - - - 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
                  - - 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
                   - 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
                    7 1 1 1 1 1 1 1 1 0 1 1 1 1 1 1 1 1 1
                     1 1 1 1 1 1 1 1 2 1 1 1 1 1 1 1 1 1
                      1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
                       1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
                        1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
                         1 1 1 1 1 1 1 1 1 1 1 1 1 1
                          1 1 1 1 1 1 1 1 1 3 1 1 1
                           1 1 1 1 1 1 1 1 1 1 1 1
                            1 6 1 1 1 1 1 1 1 1 1
                             1 1 1 1 1 1 1 1 1 1
sfp:
    symmetry: full
    geom: cartesian
    lattice pitch:
        x: 50.0
        y: 50.0
    grid contents:
        [0,0]: MC
        [1,0]: MC
        [0,1]: MC
        [1,1]: MC

Tip

We have gone through some effort to allow both pin and core grid definitions to share this input and it may improve in the future.

You may set up some kinds of grids (e.g. 1/3 and full core hex or Cartesian core loadings) using our interactive graphical grid editor described more in armi.utils.gridEditor.

../_images/gridEditor.png

An example of the Grid Editor being used on a FFTF input file

2.3.7. Custom Isotopics

In some cases (such as benchmarking a previous reactor), the default mass fractions from the material library are not what you want to model. In these cases, you may override the isotopic composition provided by the material library in this section. There are three ways to specify the isotopics: mass fractions (sum to 1.0), number densities (in atoms/barn-cm), or number fractions (sum to 1.0). For example:

custom isotopics:
    LABEL1:
        input format: mass fractions
        density: 7.79213903298633
        C: 0.000664847887388523
        CR: 0.182466356404319
        CU: 0.00323253628006144
        FE: 0.705266053783901
        MN: 0.0171714161260001
        MO: 0.00233843050046998
        NI: 0.0831976890804466
        SI: 0.00566266993741259

See the List of Nuclides for all valid entries. Note that ARMI will expand elemental nuclides to their natural isotopics in most cases (to correspond with the nuclear data library).

The (mass) density input is invalid when specifying number densities; the code will present an error message.

Material density may be specified in custom isotopics either explicitly in a mass fractions input format (shown above) or implicitly with number densities. This is fairly straightforward for the Custom material, as it has no baseline density. Density may also be specified for components using materials which have entries in the materials library. Users should be aware of the following interactions when specifying a custom density for components using a library material:

1. The library material density will not be changed. Only the component(s) with the custom isotopics entry will have the density modification.

2. Density specified by custom isotopics will override all other density modifications in the component construction phase (e.g. TD_frac entries).

3. Only the component density is changed, not other material properties are altered to account for the change in composition/density.

4. Density can only be specified using custom isotopics for non- Custom materials that have some initial density. Don’t try to make Void have mass!

Densities specified using Custom Isotopics are applied in component construction, and should be specified at the input temperature for the component. Note that when overriding the density of a library material, all other properties of that material (e.g. expansion coefficients) will continue to be used as if the component consisted of the library material. In other words, ARMI will still think the component is made out of the original material!

2.3.8. Advanced topics

2.3.8.1. Overlapping shapes

Solids of different compositions in contact with each other present complications during thermal expansion. The ARMI Framework does not perform calculations to see exactly how such scenarios will behave mechanically; it instead focuses on conserving mass. To do this, users should input a zero-dimension component linking the 2 solid components made of the special Void material. This gap will allow the 2 components to thermally expand independently while keeping track of the overlapping area.

It is important to keep track of the areas when a DerivedShape is included in a block design because ARMI calculates the derived area by taking the full area of the block and subtracting the total area of the non-DerivedShapes. If area between thermally-expanding solids was not accounted for, this would non-physically add or subtract coolant into these gaps. To model overlapping components heterogeneously, it is suggested to use a block converter.

Additionally, it should be noted that assigning mult: fuel.mult will be ever-so-slightly slower than just defining the actual value. This is because ARMI needs to find the sibling component and get the siblings mult. If you are concerned about performance at that level and don’t expect mult to change much in your case, you can replace the constant link (i.e. it does not change over time) with a YAML anchor and alias.

2.3.8.2. Component area modifications

In some scenarios, it is desired to have one component’s area be subtracted or added to another. For example, the area of the skids in a skid duct design needs to be subtracted from the interstitial coolant. The mechanism to handle this involves adding a parameter to the component to be modified after all the required ones in the form of <componentName>.add or <componentName>.sub. The component to be added or subtracted must be defined before the component that is being modified. This allows fairly complicated configurations to be modeled without explicitly defining new components.

blocks:
    rect with 100 holes:
        holes:
            shape: Cicle
            material: Sodium
            Tinput: 600
            Thot: 600
            mult: 100
            od: 0.05
        square of steel:
            shape: Square
            material: Iron
            Tinput: 25.0
            Thot: 600.0
            widthOuter: 3.0
            modArea: holes.sub      # "holes" is the name of the other component

2.3.8.3. Putting it all together to make a Block

Here is a complete fuel block definition:

blocks:
    fuel: &block_fuel
        bond:
            shape: Circle
            material: Sodium
            Tinput: 450.0
            Thot: 450.0
            id: fuel.od
            mult: fuel.mult
            od: cladding.id
        clad:
            shape: Circle
            material: HT9
            Tinput: 25.0
            Thot: 450.0
            id: 0.905
            mult: fuel.mult
            od: 1.045
        coolant:
            shape: DerivedShape
            material: Sodium
            Tinput: 450.0
            Thot: 450.0
        duct:
            shape: Hexagon
            material: HT9
            Tinput: 25.0
            Thot: 450.0
            ip: 15.2
            mult: 1.0
            op: 16.2
        fuel:
            shape: Circle
            material: UZr
            Tinput: 25.0
            Thot: 600.0
            id: 0.0
            isotopics: LABEL1
            mult: 169.0
            od: 0.757
        intercoolant:
            shape: Hexagon
            material: Sodium
            Tinput: 450.0
            Thot: 450.0
            ip: duct.op
            mult: 1.0
            op: 16.79
        wire:
            shape: Helix
            material: HT9
            Tinput: 25.0
            Thot: 450.0
            axialPitch: 30.0
            helixDiameter: 1.145
            id: 0.0
            mult: fuel.mult
            od: 0.1

2.3.8.4. Making blocks with unshaped components

Sometimes you will want to make a homogenous block, which is a mixture of multiple materials, and will not want to define an exact shape for each of the components in the block. In this case unshaped components can be used, but ARMI still requires there to be at least one component with shape to define the pitch of the block.

In the example below, the block is a rectangular pitch so one of the components is defined as a rectangle to indicate this. Its outer dimensions determine the pitch of the block. The inner dimensions can be whatever is necessary to preserve the area fraction. Note that rectangular blocks have pitch defined by two numbers, since they may not be a square. In this case the rectangle component is half the area fraction and the other two components are one quarter:

blocks:
    fuel:
        clad:
            shape: Rectangle
            material: HT9
            Tinput: 25.0
            Thot: 25.0
            lengthOuter: 3.0
            lengthInner: 2.4
            widthOuter: 2.0
            widthInner: 1.25
            mult:1.0
        fuel:
            shape: UnshapedComponent
            material: UZr
            Tinput: 25.0
            Thot: 25.0
            area = 1.5
        coolant:
            shape: UnshapedComponent
            material: Sodium
            Tinput: 25.0
            Thot: 25.0
            area = 1.5

Warning

When using this method avoid thermal expansion by setting TInput=THot, or your pitch component dimensions might change, thus changing your pitch.

Alternatively, a void (empty) component with zero area can be added for defining the pitch, and then all three components can be defined as unshaped. The downside, is there are now four components, but only three that have actual area and composition:

blocks:
    fuel:
        clad:
            shape: UnshapedComponent
            material: HT9
            Tinput: 25.0
            Thot: 25.0
            area: 3.0
        fuel:
            shape: UnshapedComponent
            material: UZr
            Tinput: 25.0
            Thot: 25.0
            area = 1.5
        coolant:
            shape: UnshapedComponent
            material: Sodium
            Tinput: 25.0
            Thot: 25.0
            area = 1.5
        PitchDefiningComponent:
            shape: Rectangle
            material: Void
            lengthOuter: 3.0
            lengthInner: 3.0
            widthOuter: 2.0
            widthInner: 2.0
            mult:1.0

This can similarly be done for hex geometry and and a hexagon with Outer Pitch (op).

Warning

The rest of the input described below are scheduled to be moved into the settings input file, since their nature is that of a setting.

2.3.9. Nuclide Flags

The nuclide flags setting allows the user to choose which nuclides they would like to consider in the problem, and whether or not each nuclide should transmute and decay. For example, sometimes you may not want to deplete trace elements in structural materials, but in other analysis you might. If the nuclide should deplete, it must have burn: true. If it is to be included in the problem at all, it must be have xs: true All nuclides that will be produced via transmutation/decay must also have burn: true, so if you add Thorium, make sure to add all other actinides in its chain. You can use the expandTo: section to list a subset of natural nuclides to expand into. If you leave this section out, a default set of nuclide flags will be applied to your problem. Remember this section when you start changing which nuclides are modeled and which ones deplete.:

# this is a YAML comment
nuclide flags:
    AL: {burn: false, xs: true}
    AM241: {burn: true, xs: true}
    C: &carbon_flags {burn: false, xs: true}    # an anchor to "carbon_flags"
    CA: *carbon_flags
    CL: *carbon_flags
    CO: *carbon_flags                           # the alias back to "carbon_flags"
    CR: *carbon_flags
    CU: *carbon_flags
    FE: *carbon_flags
    H: {burn: false, xs: true}
    MN: {burn: false, xs: true}
    MO: {burn: false, xs: true}
    N: {burn: false, xs: true}
    NA: {burn: false, xs: true}
    NI: {burn: false, xs: true}
    O: {burn: false, xs: true, expandTo: ["O16", "O17"]}
    P: {burn: false, xs: true}
    PU238: {burn: true, xs: true}
    PU239: {burn: true, xs: true}
    PU240: {burn: true, xs: true}
    PU241: {burn: true, xs: true}
    PU242: {burn: true, xs: true}
    S: {burn: false, xs: true}
    SI: {burn: false, xs: true}
    U234: {burn: false, xs: true}
    U235: {burn: true, xs: true}
    U236: {burn: true, xs: true}
    U238: {burn: true, xs: true}

The code will crash if materials used in Blocks and Components contain nuclides not defined in nuclide flags. A failure can also occur if the burn chain is missing a nuclide.

Tip

We plan to upgrade the default behavior of this to inherit from all defined materials in a problem to reduce the user-input burden.

2.4. Fuel Management Input

Fuel management in ARMI is specified through custom Python scripts that often reside in the working directory of a run (but can be anywhere if you use full paths). During a normal run, ARMI checks for two fuel management settings:

shuffleLogic

The path to the Python source file that contains the user’s custom fuel management logic

fuelHandlerName

The name of a FuelHandler class that ARMI will look for in the Fuel Management Input file pointed to by the shuffleLogic path. Since it’s input, it’s the user’s responsibility to design and place that object in that file.

Note

We consider the limited syntax needed to express fuel management in Python code itself to be sufficiently expressive and simple for non-programmers to actually use. Indeed, this has been our experience.

The ARMI Operator will call its fuel handler’s outage method before each cycle (and, if requested, during branch search calculations). The outage() method will perform bookkeeping operations, and eventually call the user-defined chooseSwaps method (located in Fuel Management Input). chooseSwaps will generally contain calls to findAssembly(), swapAssemblies() , swapCascade(), and dischargeSwap(), which are the primary fuel management operations and can be found in the fuel management module.

Also found in the user-defined Fuel Management Input module is a getFactors method, which is used to control which shuffling routines get called and at which time.

Note

See the fuelHandlers module for more details.

2.4.1. Fuel Management Operations

In the ARMI, the assemblies can be moved as units around the reactor with swapAssemblies, dischargeSwap, and swapCascade of a FuelHandler interface.

2.4.1.1. swapAssemblies

swapAssemblies is the simplest fuel management operation. Given two assembly objects, this method will switch their locations.

self.swapAssemblies(a1,a2)

2.4.1.2. dischargeSwap

A discharge swap is a simple operation that puts a new assembly into the reactor while discharging an outgoing one.

self.dischargeSwap(newIncoming,oldOutgoing)

This operation keeps track of the outgoing assembly in a AssemblyList object that the Reactor object has access to so you can see how much of what you discharged.

2.4.1.3. swapCascade

SwapCascade is a more powerful swapping function that can swap a list of assemblies in a “daisy-chain” type of operation. These are useful for doing the main overtone shuffling operations such as convergent shuffling and/or convergent-divergent shuffling. If we load up the list of assemblies, the first one will be put in the last one’s position, and all others will shift accordingly.

As an example, consider assemblies 1 through 5 in core positions A through E.:

self.swapCascade([a1,a2,a3,a4,a5])

This table shows the positions of the assemblies before and after the swap cascade.

Assembly

Position Before Swap Cascade

Position After Swap Cascade

1

A

E

2

B

A

3

C

B

4

D

C

5

E

D

Arbitrarily complex cascades can thusly be assembled by choosing the order of the assemblies passed into swapCascade.

2.4.2. Choosing Assemblies to Move

The methods described in the previous section require known assemblies to shuffle. Choosing these assemblies is the essence of fuel shuffling design. The single method used for these purposes is the FuelHandler’s findAssembly method. This method is very general purpose, and ranks in the top 3 most important methods of the ARMI altogether.

To use it, just say:

a = self.findAssembly(param='maxPercentBu',compareTo=20)

This will return the assembly in the reactor that has a maximum burnup closest to 20%. Other inputs to findAssembly are summarized in the API docs of findAssembly().

2.4.3. Fuel Management Examples

2.4.3.1. Convergent-Divergent

Convergent-divergent shuffling is when fresh assemblies march in from the outside until they approach the jump ring, at which point they jump to the center and diverge until they reach the jump ring again, where they now jump to the outer periphery of the core, or become discharged.

If the jump ring is 6, the order of target rings is:

[6, 5, 4, 3, 2, 1, 6, 7, 8, 9, 10, 11, 12, 13]

In this case, assemblies converge from ring 13 to 12, to 11, to 10, …, to 6, and then jump to 1 and diverge until they get back to 6. In a discharging equilibrium case, the highest burned assembly in the jumpRing should get discharged and the lowest should jump by calling a dischargeSwap on cascade[0] and a fresh feed after this cascade is run.

The convergent rings in this case are 7 through 13 and the divergent ones are 1 through 5 are the divergent ones.

2.4.4. Fuel Management Tips

Some mistakes are common. Follow these tips.

  • Always make sure your assembly-level types in the settings file are up to date with the grids in your bluepints file. Otherwise you’ll be moving feeds when you want to move igniters, or something.

  • Use the exclusions list! If you move a cascade and then the next cascade tries to run, it will choose your newly-moved assemblies if they fit your criteria in findAssemblies. This leads to very confusing results. Therefore, once you move assemblies, you should default to adding them to the exclusions list.

  • Print cascades during debugging. After you’ve built a cascade to swap, print it out and check the locations and types of each assembly in it. Is it what you want?

  • Watch typeNum in the database. You can get good intuition about what is getting moved by viewing this parameter.

2.5. Settings Report

This document lists all the settings in ARMI.

They are all accessible to developers through the armi.settings.caseSettings.Settings object, which is typically stored in a variable named cs. Interfaces have access to a simulation’s settings through self.cs.

ARMI Settings

Name

Description

Default

Options

Tin

The inlet temperature of the reactor in C

360.0

Tout

The outlet temperature of the reactor in C

510.0

acceptableBlockAreaError

The limit of error between a block’s cross- sectional area and the reference block used during the assembly area consistency check

1e-05

aclpDoseLimit

Dose limit in dpa used to position the above-core load pad(if one exists)

80.0

assemFlagsToSkipAxialExpa nsion

Assemblies that match a flag on this list will not be axially expanded.

[]

assemPowSummary

Print a summary of how much power is in each assembly type at every timenode

False

assemblyRotationAlgorithm

The algorithm to use to rotate the detail assemblies while shuffling

['', 'buReducingAssemblyR otation', 'simpleAssemblyRotation']

assemblyRotationStationar y

Whether or not to rotate assemblies that are not shuffled.This can only be True if ‘rotation’ is true.

False

autoGenerateBlockGrids

Should block blueprints attempt to auto-generate a spatial grid upon construction? This feature makes heavy use of multi-index locations, which are not yet universally supported.

True

automaticVariableMesh

Flag to let ARMI add additional mesh points if the neutronics mesh is too irregular

False

availabilityFactor

Availability factor of the plant. This is the fraction of the time that the plant is operating. If variable, use availabilityFactors setting.

1.0

availabilityFactors

List of availability factor of each cycle as a fraction (fraction of time plant is not in an outage). R is repeat. For example [0.5, 1.0, ‘9R’] is 1 50% followed by 10 100%. Empty list is constant duration set by availabilityFactor.

[]

axialExpansion

Perform axial fuel expansion. This will adjust fuel block lengths.

False

axialMeshRefinementFactor

Multiplicative factor on the Global Flux number of mesh per block. Used for axial mesh refinement.

1

bcCoefficient

Value for the parameter A of the generalized boundary condition.

0.0

beta

Individual precursor group delayed neutron fractions

None

bondRemoval

Toggles fuel performance bond removal. This will remove thermal bond from the fuel.

False

boundaries

External Neutronic Boundary Conditions. Reflective does not include axial.

Extrapolat ed

['Extrapolated', 'Reflective', 'Infinite', 'ZeroSurfaceFlux', 'ZeroInwardCurrent', 'Generalized']

branchVerbosity

Verbosity of the non- primary MPI nodes

error

['debug', 'extra', 'info', 'important', 'prompt', 'warning', 'error']

buGroups

The range of burnups where cross-sections will be the same for a given assembly type (units of %FIMA)

[10, 20, 30, 100]

burnChainFileName

Path to YAML file that has the depletion chain defined in it

burn- chain.yaml

burnSteps

Number of depletion substeps, n, in one cycle. Note: There will be n+1 time nodes and the burnup step time will be computed as cycle length/n when the simple cycles input format is used.

4

burnupPeakingFactor

The peak/avg factor for burnup and DPA. If it is not set the current flux peaking is used (this is typically conservatively high).

0.0

circularRingMode

Toggle between circular ring definitions to hexagonal ring definitions

False

circularRingOrder

Order by which locations are sorted in circular rings for equilibrium shuffling

angle

['angle', 'distance', 'distanceSmart']

circularRingPitch

The relative pitch to be used to define a single circular ring in circular shuffling

1.0

claddingStrain

Evaluate cladding strain.

False

claddingWastage

Evaluate cladding wastage.

False

clearXS

Delete all cross section libraries before regenerating them.

False

comment

A comment describing this case

copyFilesFrom

A list of files that need to be copied at the start of a run.

[]

copyFilesTo

A list of directories to copy provided files into at the start of a run.This list can be of length zero (copy to working dir), 1 (copy all files to the same place), or it must be the same length as copyFilesFrom

[]

coverage

Turn on coverage report generation which tracks all the lines of code that execute during a run

False

coverageConfigFile

User-defined coverage configuration file

crossSectionControl

Data structure defining how cross sections are created

<XSSetting s with XS IDs dict_k eys([])>

customFuelManagementIndex

An index that determines which of various options is used in management. Useful for optimization sweeps.

0

cycleLength

Duration of one single cycle in days. If availabilityFactor is below 1, the reactor will be at power less than this. If variable, use cycleLengths setting.

365.242199

cycleLengths

List of durations of each cycle in days. The at- power duration will be affected by availabilityFactor. R is repeat. For example [100, 150, ‘9R’] is 1 100 day cycle followed by 10 150 day cycles. Empty list is constant duration set by cycleLength.

[]

cycles

YAML list defining the cycle history of the case. Options at each cycle include: name, cumulative days, step days, availability factor, cycle length, burn steps, and power fractions. If specified, do not use any of the case settings cycleLength(s), availabilityFactor(s), powerFractions, or burnSteps. Must also specify nCycles and power.

[]

cyclesSkipTightCouplingIn teraction

List of cycle numbers skip tight coupling interaction for. Will still update component temps, etc during these cycles, will just not iterate a second (or more) time.

[]

db

Write the state information to a database at every timestep

True

dbStorageAfterCycle

Only store cycles after this cycle in the database (to save storage space)

0

debugDB

Write state to DB with a unique timestamp or label.

False

debugMem

Turn on memory debugging options to help find problems with the code

False

debugMemSize

Show size of objects during memory debugging

False

decayConstants

Individual precursor group delayed neutron decay constants

None

defaultSnapshots

Generate snapshots at BOL, MOL, and EOL.

False

deferredInterfaceNames

Interfaces to delay the normal operations of for special circumstance problem avoidance

[]

deferredInterfacesCycle

The supplied list of interface names in deferredInterfaceNames will begin normal operations on this cycle number

0

detailAllAssems

All assemblies will have ‘detailed’ treatment. Note: This option is interpreted differently by different modules.

False

detailAssemLocationsBOL

Assembly locations for assemblies that will have ‘detailed’ treatment. This option will track assemblies in the core at BOL. Note: This option is interpreted differently by different modules.

[]

detailAssemNums

Assembly numbers(IDs) for assemblies that will have ‘detailed’ treatment. This option will track assemblies that not in the core at BOL. Note: This option is interpreted differently by different modules.

[]

detailedAxialExpansion

Allow each assembly to expand independently of the others. Results in non-uniform axial mesh. Neutronics kernel must be able to handle.

False

disableBlockTypeExclusion InXsGeneration

Use all blocks in a cross section group when generating a representative block. When this is disabled only fuel blocks will be considered

False

doTH

Activate thermal hydraulics calculations using the physics module defined in thKernel

False

dpaPerFluence

A quick and dirty conversion that is used to get dpaPeak by multiplying the factor and fastFluencePeak

4.01568627 451e-22

dpaXsSet

The cross sections to use when computing displacements per atom.

dpa_EBRII_ HT9

['', 'dpa_EBRII_INC600', 'dpa_EBRII_INCX750', 'dpa_EBRII_HT9', 'dpa_EBRII_PE16', 'dpa_EBRII_INC625']

dumpSnapshot

List of snapshots to perform detailed reactor analysis, such as reactivity coefficient generation.

[]

eigenProb

Is this a eigenvalue problem or a fixed source problem?

True

epsEig

Convergence criteria for calculating the eigenvalue in the global flux solver

1e-07

epsFSAvg

Convergence criteria for average fission source

1e-05

epsFSPoint

Convergence criteria for point fission source

1e-05

eqDirect

Does the equilibrium search with repetitive shuffing but with direct shuffling rather than the fast way

False

existingFixedSource

Specify an exiting fixed source input file.

['', 'FIXSRC', 'VARSRC']

explicitRepeatShuffles

Path to file that contains a detailed shuffling history that is to be repeated exactly.

fgRemoval

Toggles fuel performance fission gas removal. This will remove fission gas from the fuel.

False

fissionGasYieldFraction

The fraction of gaseous atoms produced per fission event, assuming a fission product yield of 2.0

0.25

fluxRecon

Perform detailed flux and power reconstruction

False

forceDbParams

A list of parameter names that should always be written to the database, regardless of their Parameter Definition’s typical saveToDB status. This is only honored if the DatabaseInterface is used.

[]

fpModel

This setting is used to determine how fission products are treated in an analysis. By choosing noFissionProducts, no fission products will be added. By selecting, infinitelyDilute, lumped fission products will be initialized to a very small number on the blocks/components that require them. By choosing MO99, the fission products will be represented only by Mo-99. This is a simplistic assumption that is commonly used by fast reactor analyses in scoping calculations and is not necessarily a great assumption for depletion evaluations. Finally, by choosing explicitFissionProducts the fission products will be added explicitly to the blocks/components that are depletable. This is useful for detailed tracking of fission products.

infinitely Dilute

['noFissionProducts', 'infinitelyDilute', 'MO99', 'explicitFissionP roducts']

fpModelLibrary

This setting should be used when fpModel is set to explicitFissionPr oducts. It is used in conjunction with any nuclideFlags defined in the blueprints to configure all the nuclides that are modeled within the core. Selecting any library option will add all nuclides from the selected library to the model so that analysts do not need to change their inputs when modifying the fission product treatment for calculations.

['', 'MC2-3']

freshFeedType

The type of fresh fuel added to the core, used in certain pre-defined fuel shuffling logic sequences.

feed fuel

['feed fuel', 'igniter fuel', 'inner driver fuel']

fuelHandlerName

The name of the FuelHandler class in the shuffle logic module to activate

fuelPerformanceEngine

Fuel performance engine that determines fission gas removal, bond removal, axial growth, wastage, and cladding strain.

['']

genReports

Employ the use of the reporting utility for ARMI, generating HTML and ASCII summaries of the run

True

genXS

Generate multigroup cross sections for the selected particle type(s) using the specified lattice physics kernel (see Lattice Physics tab). When not set, the XS library will be auto- loaded from an existing ISOTXS in the working directory, but fail if there is no ISOTXS.

['', 'Neutron', 'Neutron and Gamma']

geomFile

Input file containing BOL core map

globalFluxActive

Calculate the global flux at each timestep for the selected particle type(s) using the specified neutronics kernel (see Global Flux tab).

Neutron

['', 'Neutron', 'Neutron and Gamma']

gridPlateDpaXsSet

The cross sections to use for grid plate blocks DPA when computing displacements per atom.

dpa_EBRII_ HT9

['', 'dpa_EBRII_INC600', 'dpa_EBRII_INCX750', 'dpa_EBRII_HT9', 'dpa_EBRII_PE16', 'dpa_EBRII_INC625']

groupStructure

Energy group structure to use in neutronics simulations

ANL33

['ANL9', 'ANL33', 'ANL70', 'ANL116', 'ANL230', 'ANL703', 'ANL1041', 'ANL2082', 'ARMI33', 'ARMI45', 'CINDER63', '348']

growToFullCoreAfterLoad

Grows from 1/3 to full core after loading a 1/3 symmetric snapshot. Note: This is needed when a full core model is needed and the database was produced using a third core model.

False

independentVariables

List of (independentVarName, value) tuples to inform optimization post- processing

[]

infiniteDiluteCutoff

Do not model nuclides with density less than this cutoff. Used with PARTISN and SERPENT.

1e-10

initializeBurnChain

This setting is paired with the burnChainFileName setting. When enabled, this will initialize the burn-chain on initializing the case and is required for running depletion calculations where the transmutations and decays are controlled by the framework. If an external software, such as ORIGEN, contains data for the burn-chain already embedded then this may be disabled.

True

inners

XY and Axial partial current sweep inner iterations. 0 lets the neutronics code pick a default.

0

inputHeightsConsideredHot

This is a flag to determine if block heights, as provided in blueprints, are at hot dimensions. If false, block heights are at cold/as-built dimensions and will be thermally expanded as appropriate.

True

jumpRingNum

The number of hex rings jumped when distributing the feed assemblies in the alternating concentric rings or checkerboard shuffle patterns (convergent / divergent shuffling).

8

latticePhysicsFrequency

Define the frequency at which cross sections are updated with new lattice physics interactions.

BOC

['never', 'BOL', 'BOC', 'everyNode', 'firstCoupledIteration', 'all']

levelsPerCascade

The number of moves made per cascade when performing convergent or divergent shuffle patterns.

14

lfpCompositionFilePath

Path to the file that contains lumped fission product composition definitions (e.g. equilibrium yields). This is unused when the explicitFissionProducts or MO99 modeling options are selected.

referenceF issionProd ucts.dat

loadFromDBEveryNode

Every node loaded from reference database

False

loadPadElevation

The elevation of the bottom of the above-core load pad (ACLP) in cm from the bottom of the upper grid plate. Used for calculating the load pad dose

0.0

loadPadLength

The length of the load pad. Used to compute average and peak dose.

0.0

loadStyle

Description of how the ARMI case will be initialized

fromInput

['fromInput', 'fromDB']

loadingFile

The blueprints/loading input file path containing component dimensions, materials, etc.

lowPowerRegionFraction

Description needed

0.05

makeAllBlockLFPsIndepende nt

Flag to make all blocks have independent lumped fission products. Note that this is forced to be True when the explicitFissionProducts modeling option is selected or an interface named mcnp is on registered on the operator stack.

False

materialNamespaceOrder

Ordered list of Python namespaces for finding materials by class name. This allows users to choose between different implementations of reactor materials. For example, the framework comes with a basic UZr material, but power users will want to override it with their own UZr subclass. This allows users to specify to get materials out of a plugin rather than from the framework.

[]

minMeshSizeRatio

This is the minimum ratio of mesh sizes (dP1/(dP1 + dP2)) allowable – only active if automaticVariableMesh flag is set to True

0.15

minimumFissileFraction

Minimum fissile fraction (fissile number densities / heavy metal number densities).

0.045

minimumNuclideDensity

Density to use for nuclides and fission products at infinite dilution. This is also used as the minimum density considered for computing macroscopic cross sections. It can also be passed to physics plugins.

1e-15

moduleVerbosity

Verbosity of any module- specific loggers that are set

{}

mpiTasksPerNode

Number of independent processes that are allocated to each cluster node. 0 means 1 process per CPU.

0

nCycles

Number of cycles that will be simulated. Fuel management happens at the beginning of each cycle. Can include active (full- power) cycles as well as post-shutdown decay-heat steps. For restart cases, this value should include both cycles from the restart plus any additional cycles to be run after startCycle.

1

neutronicsKernel

The neutronics / depletion solver for global flux solve.

neutronicsType

The type of neutronics solution that is desired.

real

['real', 'adjoint', 'both']

nonUniformAssemFlags

Assemblies that match a flag group on this list will not have their mesh changed with the reference mesh of the core for uniform mesh cases (non-detailed axial expansion). Another plugin may need to make the mesh uniform if necessary.

[]

numProcessors

Number of CPUs to request on the cluster

1

numberMeshPerEdge

Number of mesh per block edge for finite- difference planar mesh refinement.

1

operatorLocation

The path to the operator code to execute for this run (for custom behavior)

outers

XY and Axial partial current sweep max outer iterations.

100

outputCacheLocation

Location where cached calculations are stored and retrieved if exactly the same as the calculation requested. Empty string will not cache.

outputFileExtension

The default extension for plots

jpg

['jpg', 'png', 'svg', 'pdf']

plotShuffleArrows

Make plots with arrows showing each move.

False

plots

Generate additional plots throughout the ARMI analysis

False

power

Nameplate thermal power of the reactor. Can be varied by setting the powerFractions setting.

0.0

powerDensity

Thermal power of the Reactor, per gram of Heavy metal mass. Ignore this setting if the power setting is non- zero.

0.0

powerFractions

List of power fractions at each cycle (fraction of rated thermal power the plant achieves). R is repeat. For example [0.5, 1.0, ‘9R’] is 1 50% followed by 10 100%. Specify zeros to indicate decay-only cycles (i.e. for decay heat analysis). None implies always full rated power.

[]

profile

Turn on the profiler for the submitted case. The profiler results will not include all import times.

False

reallySmallRun

Clean up files at the beginning of each cycle (BOC)

False

reloadDBName

Name of the database file to load initial conditions from

removePerCycle

The number of fuel assemblies removed per cycle at equilibrium.

3

restartNeutronics

Restart global flux case using outputs from last time as a guess

False

runLatticePhysicsBeforeSh uffling

Forces the Generation of Cross Sections Prior to Shuffling the Fuel Assemblies. Note: This is recommended when performing equilibrium shuffling branching searches.

False

runType

Type of run that this is, e.g. a normal run through all cycles, a snapshot- loaded reactivity coefficient run, etc.

Standard

['Standard', 'Equilibrium', 'Snapshots']

savePhysicsFiles

List of snapshots to dump reactor physics kernel input and output files. Can be used to perform follow-on analysis.

[]

shuffleLogic

Python script written to handle the fuel shuffling for this case. This is user-defined per run as a dynamic input.

skipCycles

Number of cycles to be skipped during the calculation. Note: This is typically used when repeating only a portion of a calculation or repeating a run.

0

smallRun

Clean up intermediate files after the run completes (EOL)

False

sortReactor

Deprecation Warning! This setting will be remove by 2024.

True

startCycle

Cycle number to continue calculation from. Database will load from the time step just before. For snapshots use dumpSnapshot.

0

startNode

Timenode number (0 for BOC, etc.) to continue calulation from. Database will load from the time step just before.

0

stationaryBlockFlags

Blocks with these flags will not move in moves. Used for fuel management.

['GRID_PLA TE']

summarizeAssemDesign

Print a summary of the assembly design details at BOL

True

syncDbAfterWrite

Copy the output database from the fast scratch space to the shared network drive after each write.

False

targetK

Target criticality (k-effective) for cycle length, branch, and equilibrium search

1.005

thKernel

Name of primary T/H solver in this run

False

tightCoupling

Boolean to turn on/off tight coupling

False

tightCouplingMaxNumIters

Maximum number of iterations for tight coupling.

4

tightCouplingSettings

Data structure defining the tight coupling parameters and convergence criteria for each interface.

<TightCoup lingSettin gs with Interface functions `` ``dict_keys( [])>

timelineInclusionCutoff

Timers who are not active for this percent of the run will not be presented in the timeline graphic

0.03

tolerateBurnupChange

Burnup window for computing cross sections. If the prior cross sections were computed within the window, new cross sections will not be generated and the prior calculated cross sections will be used.

0.0

trace

Activate Python trace module to print out each line as it’s executed

False

trackAssems

Track assemblies for detailed fuel histories. For instance, assemblies are tracked after they come out of a reactor by putting them in a Spent Fuel Pool. This might be necessary for your work, but it certainly increases the memory usage of the program.

False

uniformMeshMinimumSize

Minimum mesh size used when generating an axial mesh for the uniform mesh converter. Providing a value for this setting allows fuel and control material boundaries to be enforced better in uniform mesh.

None

userPlugins

YAML list defining the locations of UserPlugin subclasses. You can enter the full armi import path: armi.test.test_wha t.MyPlugin, or you can enter the full file path: /path/to/my/pluginz.py:My Plugin

[]

verbosity

How verbose the output will be

info

['debug', 'extra', 'info', 'important', 'prompt', 'warning', 'error']

versions

Versions of ARMI, and any Apps or Plugins that register a version here.

{}

xsBlockRepresentation

The type of averaging to perform when creating cross sections for a group of blocks

Average

['Median', 'Average', 'FluxWeightedAverage', 'ComponentAverage1DSlab']

xsBucklingConvergence

Convergence criteria for the buckling iteration if it is available in the lattice physics solver

1e-05

xsEigenvalueConvergence

Convergence criteria for the eigenvalue in the lattice physics kernel

1e-05

xsKernel

Method to determine broad group cross sections for assemblies

MC2v3

['', 'MC2v2', 'MC2v3', 'MC2v3-PARTISN', 'SERPENT']

xsScatteringOrder

Scattering order for the lattice physics calculation

3

zeroOutNuclidesNotInDB

If a nuclide was added to the problem after a previous case was run, deactivate this to let it survive in a restart run

True

zoneDefinitions

Manual definitions of zones as lists of assembly locations (e.g. ‘zoneName: loc1, loc2, loc3’) . Zones are groups of assemblies used by various summary and calculation routines.

[]