4. User Guide¶

This section describes the installation and use of the DIF3D ARMI plugin and its demo application.

4.1. Installation¶

Installation of ARMI plugins involves configuring the plugin package and its dependencies to be importable from a Python environment. This often involves creating a Python virtual environment and installing the package using the pip Python package manager, though other options may be acceptable depending on the user’s environment. In this section, the recommended installation instructions are provided.

4.1.1. Prerequisites¶

The DIF3D ARMI plugin depends on ARMI itself, and a collection of other publicly-available Python packages. It is recommended to install all of these within a Python virtual environment. The ARMI Installation Documentation provides good guidance on how to create a virtual environment and install ARMI into it.

In addition to the dependencies needed to make ARMI and the DIF3D plugin run, there are some optional dependencies that are needed to run the tests and generate these documents. These extra dependencies are expressed in the dev package extras, and can be installed by appending [dev] to the pip install target. Examples of this are shown below.

4.1.2. Installing the code¶

The plugin is written in pure Python and does not need to be compiled. Once the code is extracted in a folder, there are several options for installing it. The easiest way to do this is to install it in “editable” mode; run:

> pip install -e .

to install it into your virtual environment. The -e flag tells pip to place a link to the code in site-packages, rather than copying the files themselves. If it is desired to generate the documentation or run unit tests, the above can be modified to install the extra dependencies:

> pip install -e .[dev]

Alternatively, the code can be packaged and installed. One way to do this is to install the wheel package, build a wheel, and install that wheel into your environment. The following commands would accomplish this:

> pip install wheel
> python setup.py bdist_wheel
> pip install dist/inl_dif3d-1.0-py3-none-any.whl

At this point it should be possible to import the DIF3D plugin modules, and to run the main demonstration application, dif3ddemo.

4.1.3. External physics codes¶

In addition to the Python code that makes ARMI and the DIF3D plugin operate, the Dragon and DIF3D codes will need to be present on the system in order to actually run them. Obtaining, compiling, and installing these is beyond the scope of this document. Once installed, it is recommended that they be available via the system PATH to avoid needing to define their precise locations through the dragonExePath and dif3dExePath settings.

Note

DRAGON is used in the demo application to generate multigroup cross sections. Other lattice physics codes may be used in its place if desired.

4.2. Running the test suite¶

4.2.1. Unit tests¶

The plugin comes with several self-contained unit tests. To run them, execute the following in the root folder:

> pytest

The tests themselves rely on a handful of unit test fixtures, which are essentially binary and ASCII output files from DIF3D that the units tests operate upon. These are committed to the source repository, and should already be present. In the event that they need to be updated, this can be done by running the dif3ddemo application with its make-fixture-suite and copy-fixture-files entry points. It is recommended to do this somewhere outside of the main source tree:

> dif3ddemo make-fixture-suite
    --dragonDataPath=/path/to/dragon/data/draglibendfb8r0SHEM361
    --dragonExePath=/path/to/dragon.exe
    --dif3dExePath=/path/to/dif3d.exe

Tip

On Windows you may have to eliminate or escape the line breaks to get that to execute.

From the same working directory that the test fixture cases were run above, they can be copied to their appropriate location with:

> dif3ddemo copy-fixture-files

This will divine the appropriate target location relative to the dif3ddemo application itself.

4.3. User settings¶

Many settings can be configured by the user at runtime and are 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. Table 4.1 lists all settings that are provided by the DIF3D ARMI plugin. Additional settings, defined by the ARMI Framework and its built-in global-flux plugin also affect the behavior of this plugin, as it implements the GlobalFluxInterface interface. Of these, the neutronicsKernel setting is the most important, as it must be set to "DIF3D-Nodal", "DIF3D-FD", or "VARIANT" for the interface to be activated.

Table 4.1 DIF3D Plugin Settings¶
Name	Description	Default
`asympExtrapOfNodalCalc`	Perform asymptotic source extrapolation on the the nodal outer iterations. Applies to DIF3D-Nodal and VARIANT.
`asympExtrapOfOverRelaxCalc`	Asymptotic source extrapolation of power iterations used to estimate the spectral radius of each within group iteration matrix. Intended for problems with overrelaxation factor > 1.8.
`coarseMeshRebalance`	Sets the coarse-mesh rebalance acceleration to something other than the default.
`d3dMem`	POINTR container array size in extended core memory for A.DIF3D card of DIF3D/REBUS. Max recommended=159999000	`24000000`
`d3dMem2`	POINTR container array size in fast core memory in REAL*8 words in A.DIF3D card of DIF3D/REBUS. Max recommended=40000000	`40000000`
`dif3dExePath`	The path do the DIF3D executable	`dif3d`
`epsBurnTime`	Burn time eps (Cycle length convergence. Set to 1.0 if the cycle length is known.)	`1.0`
`epsCyclic`	max relative error in isotope stage density during cyclics (0.001)	`0.001`
`epsNdens`	max relative error in any isotope in region density (0.001)	`0.001`
`erf`	Error reduction factor to be achieved by each series of inner iteration for each group during a shape calculation in DIF3D/REBUS. Reduce to 0.01 if dominance ratio estimate is sporadic, or if pointwise fission source convergence is not monotonic.	`0.04`
`inners`	XY and Axial partial current sweep inner iterations. 0 is let DIF3D pick or use default if can’t pick.
`listIsotxs`	list ISOTXS in the DIF3D output file
`neglectFis`	Any pointwise fission source will be neglected in the pointwise fission source convergence test if it is less than this factor times the RMS fission source in DIF3D/REBUS	`0.001`
`neutronicsOutputsToSave`	Defines outputs from DIF3D-based neutronics kernel to be copied from the fast path to the network drive for inspection, restarts, debugging, etc.	`Input/Output`
`nipMem`	Size of main core storage array for geometry processing module (GNIP4C) in A.NIP card of DIF3D/REBUS. Max recommended=40000000	`40000000`
`nodalApproxXY`	Approximation controls in XY-Plane (LMN). L can either be 0 (diffusion) or 1 (transport), M is the flux approximation order (2: quadratic, 3: cubic, or 4: quartic), and N is the leakage approximation order (0: constant or 2: quadratic). For details, see A.DIF3D file formats document, under TYPE 10.	`40`
`nodalApproxZ`	Approximation controls in Z-direction. M is the flux approximation order (2: quadratic, 3: cubic, or 4: quartic), and N is the leakage approximation order (0: constant or 2: quadratic). For details, see A.DIF3D file formats document, under TYPE 10.	`32`
`outers`	Max number of outer iterations to converge	`100`
`useRadialInnerIterationAlgorithm`	Use the VARIANT Radial Inner Iteration Algorithm which is helpful for cases with small node mesh. Type 12 card in A.DIF3D
`variantNodalSpatialApproximation`	The Nodal Spatial polynomial approximation in VARIANT. See Type 12 card in A.DIF3D for information.	`20501`
`variantTransportAndScatterOrder`	The flux/leakage angle and scattering orders to use with neutronics kernel VARIANT.
`writeDif3dDb`	If enabled, a database will be created containing the results of the most recent DIF3D invocation before converting back to the input mesh. This is useful for visualizing/analyzing the direct results of the DIF3D run without any mesh conversions taking place.
`xsMem`	Size of main core storage array for cross section processing modules. Max recommended=40000000	`40000000`

4.4. Input Data¶

State information required on the ARMI data model before this plugin can operate includes the following:

A Core system populated with Blocks that have number-density compositions (typically provided by user input and/or depletion modules). Any reactor model that is loaded from an ARMI Blueprints file will contain a .core member that functions in this capacity.
A microscopic cross section library provided by the user or a lattice physics plugin, in ISOTXS format. In all of the examples presented, this was produced by the open-source ARMI DRAGON plugin, which is included in the dif3ddemo app. Running the dif3ddemo run entry point will lead to the creation of such an ISOTXS file before attempting to run DIF3D.

4.5. Output Data¶

The DIF3D plugin writes the DIF3D neutronics results to the ARMI data model on the following Parameters.

4.5.1. Core parameters¶

A subset of the core parameters provided by the generic neutronics plugin are written by this plugin. Specifically:

keff

4.5.2. Block parameters¶

A subset of the block parameters provided by the generic neutronics plugin are written by this plugin. Specifically:

pdens
ppdens
power
flux
fluxPeak
mgFlux
fluxAdj
adjMgFlux

In addition to the parameters supplied directly from the DIF3D output, several other flux-derived parameters are also calculated when the DIF3D solution is mapped from the DIF3D mesh back to the as-input ARMI mesh. Re-calculated values include:

rateCap
rateFis
rateProdN2n
rateProdFis
rateAbs

The exact behavior of the mapped and recalculated parameter values is governed by the armi.physics.neutronics.globalFlux.globalFluxInterface.calcReactionRates() function and armi.reactor.converters.uniformMesh.NeutronicsUniformMeshConverter class. This behavior is demonstrated in Results.