armi.physics.fuelCycle.fuelHandlers module

This module handles fuel management operations such as shuffling, rotation, and fuel processing (in fluid systems).

The FuelHandlerInterface instantiates a FuelHandler, which is typically a user-defined subclass the FuelHandler object in custom shuffle-logic input files. Users point to the code modules with their custom fuel handlers using the shuffleLogic and fuelHandlerName settings, as described in /user/inputs/fuel_management. These subclasses override chooseSwaps that determine the particular shuffling of a case.

This module also handles repeat shuffles when doing a restart.

class armi.physics.fuelCycle.fuelHandlers.FuelHandler(operator)

Bases: object

A fuel handling machine can move fuel around the core and reactor.

It makes decisions on how to shuffle fuel based on user specifications. It provides some supervisory data tracking, such as having the ability to print out information about all moves that happened in a cycle (without the user needing to explicitly track this information).

To use this, simply create an input Python file and point to it by path with the fuelHandler setting. In that file, subclass this object.

property cycle

Link to the current cycle number.

Notes

This retains backwards compatibility with previous fuel handler inputs.

property cs

Link to the Case Settings object.

property r

Link to the Reactor object.

outage(factor=1.0)

Simulates a reactor reload outage. Moves and tracks fuel.

This sets the moveList structure.

chooseSwaps(shuffleFactors=None)

Moves the fuel around or otherwise processes it between cycles.

static getFactorList(cycle, cs=None, fallBack=False)

Return factors between 0 and 1 that control fuel management.

This is the default shuffle control function. Usually you would override this with your own in a custom shuffleLogic.py file. For more details about how this works, refer to /user/inputs/fuel_management.

This will get bound to the default FuelHandler as a static method below. This is done to allow a user to mix and match FuelHandler class implementations and getFactorList implementations at run time.

Notes

Ultimately, this approach will likely get replaced using the plugin framework, but we aren’t there yet.

prepCore()

Aux function to run before XS generation (do moderation, etc).

prepSearch(*args, **kwargs)

Optional method that can be implemented in preparation of shuffling.

Often used to prepare the scope of a shuffling branch search.

Notes

This was used historically to keep a long-lived fuel handler in sync with the reactor and can now technically be removed from the API, but many historical fuel management inputs still expect it to be called by the framework, so here it remains. New developments should avoid using it. Most code using it has been refactored to just use a _prepSearch private method.

It now should not be used and will trigger a DeprecationWarning in the constructor. It’s still here because old user-input code calls the parent’s prepSearch, which is this.

findAssembly(targetRing=None, width=(0, 0), param=None, compareTo=None, forceSide=None, exclusions=None, typeSpec=None, mandatoryLocations=None, zoneList=None, excludedLocations=None, minParam=None, minVal=None, maxParam=None, maxVal=None, findMany=False, coords=None, exactType=False, acceptFirstCandidateRing=False, blockLevelMax=False, findFromSfp=False, maxNumAssems=None, circularRingFlag=False)

Search reactor for assemblies with various criterion. Primarily for shuffling.

Parameters:

• targetRing (int, optional) – The ring in which to search

• width (tuple of integers) – A (size, side) tuple where size is the number of rings on either side to also check. side=1: only look in higher, -1: only look lower, 0: both sides

• param (string, optional) – A block (if blockLevelMax) or assem level param name such as ‘power’ or ‘percentBu’ (requires compareTo).

• compareTo (float or Assembly instance) – an assembly to be compared to. Alternatively, a floating point number to compare to. Even more alternatively, an (assembly,mult) or (float,mult) tuple where mult is a multiplier. For example, if you wanted an assembly that had a bu close to half of assembly bob, you’d give param=’percentBu’, compareTo=(bob,0.5) If you want one with a bu close to 0.3, you’d do param=’percentBu’,compareTo=0.3. Yes, if you give a (float, multiplier) tuple, the code will make fun of you for not doing your own math, but will still operate as expected.

• forceSide (bool, optional) –

  requires the found assembly to have either 1: higher, -1: lower, None: any param than

  compareTo

• exclusions (list, optional) – List of assemblies that will be excluded from the search

• minParam (float or list, optional) – a parameter to compare to minVal for setting lower bounds. If list, must correspond to parameters in minVal in order.

• maxParam (float or list, optional) – a parameter to compare to maxVal for setting upper bounds of acceptable assemblies. If list, must correspond to parameters in maxVal in order.

• minVal (float or list, optional) –

  a value or a (parameter, multiplier) tuple for setting lower bounds

  For instance, if minParam = ‘timeToLimit’ and minVal=10, only assemblies with timeToLimit higher than 10 will be returned. (Of course, there is also maxParam and maxVal)

• maxVal (float or list, optional) – a value or a (parameter, multiplier) tuple for setting upper bounds

• mandatoryLocations (list, optional) –

  a list of string-representations of locations in the core for limiting the search to several places

  Any locations also included in excludedLocations will be excluded.

• excludedLocations (list, optional) – a list of string-representations of locations in the core that will be excluded from the search

• zoneList (list, optional) – name of a zone defined in settings.py that will be picked from. Under development

• findMany (bool, optional) – If True, will return a list of assembies that match. Don’t give a param.

• typeSpec (Flags or list of Flags, optional) – only assemblies with this type list will be returned. If none, only fuel will be found.

• coords (tuple, optional) – x,y tuple in cm. the fuel handler will try to find an assembly with a center closest to that point

• exactType (bool, optional) – require type to be exactly equal to what’s in the type list. So Flags.IGNITER | Flags.FUEL is not Flags.INNER | Flags.IGNITER | Flags.FUEL

• acceptFirstCandidateRing (bool, optional) – takes the first assembly found in the earliest ring (without searching all rings for a maxBu, for example) So if the candidate rings are 1-10 and we’re looking for igniter fuel with a maxBurnup, we don’t get the max burnup in all those rings, but rather the igniter with the max burnup in the ring closest to 1. If there are no igniters until ring 4, you will get an igniter in ring 4.

• blockLevelMax (bool, optional) – If true, the param to search for will be built as the maximum block-level param of this name instead of the assembly param. This avoids the need to assign assembly level params sometimes. default: false.

• findFromSfp (bool, optional) – if true, will look in the spent-fuel pool instead of in the core.

• maxNumAssems (int, optional) – The maximum number of assemblies to return. Only relevant if findMany==True

• circularRingFlag (bool, optional) – A flag to toggle on using rings that are based on distance from the center of the reactor

Notes

The call signature on this method may have gotten slightly out of hand as valuable capabilities were added in fuel management studies. For additional expansion, it may be worth reconsidering the design of these query operations ;).

Returns:

• Assembly instance or assemList of assembly instances that match criteria, or None if none

• match

Examples

This returns the feed fuel assembly in ring 4 that has a burnup closest to 100% (the highest burnup assembly):

feed = self.findAssembly(targetRing=4,
                         width=(0,0),
                         param='maxPercentBu',
                         compareTo=100,
                         typeSpec=Flags.FEED | Flags.FUEL)

static isAssemblyInAZone(zoneList, a)

Does the given assembly in one of these zones.

swapAssemblies(a1, a2)

Moves a whole assembly from one place to another.

Parameters:

• a1 (Assembly) – The first assembly

• a2 (Assembly) – The second assembly

See also

dischargeSwap

swap assemblies where one is outside the core and the other is inside

dischargeSwap(incoming, outgoing)

Removes one assembly from the core and replace it with another assembly.

Parameters:

• incoming (Assembly) – The assembly getting swapped into the core.

• outgoing (Assembly) – The assembly getting discharged out the core.

See also

swapAssemblies

swaps assemblies that are already in the core

swapCascade(assemList)

Perform swaps on a list of assemblies.

Notes

[goingOut,inter1,inter2,goingIn] will go to [inter1, inter2, goingIn, goingOut] in terms of positions or, in ASCII art:

 >---------------v
 |               |
[A  <- B <- C <- D]

repeatShufflePattern(explicitRepeatShuffles)

Repeats the fuel management from a previous ARMI run.

Parameters:

explicitRepeatShuffles (str) – The file name that contains the shuffling history from a previous run

Returns:

moved – list of assemblies that moved this cycle

Return type:

list

Notes

typically the explicitRepeatShuffles will be “caseName”+”-SHUFFLES.txt”

See also

doRepeatShuffle

Performs moves as processed by this method

processMoveList

Converts a stored list of moves into a functional list of assemblies to swap

makeShuffleReport

Creates the file that is processed here

static readMoves(fname)

Reads a shuffle output file and sets up the moves dictionary.

Parameters:

fname (str) – The shuffles file to read

Returns:

moves – A dictionary of all the moves. Keys are the cycle number. Values are a list of tuples, one tuple for each individual move that happened in the cycle. The items in the tuple are (oldLoc, newLoc, enrichList, assemType). Where oldLoc and newLoc are str representations of the locations and enrichList is a list of mass enrichments from bottom to top.

Return type:

dict

See also

repeatShufflePattern

reads this file and repeats the shuffling

outage

creates the moveList in the first place.

makeShuffleReport

writes the file that is read here.

static trackChain(moveList, startingAt, alreadyDone=None)

Builds a chain of locations based on starting location.

Notes

Takes a moveList and extracts chains. Remembers all it touches. If A moved to B, C moved to D, and B moved to C, this returns A, B, C ,D.

Used in some monte carlo physics writers and in repeatShufflePattern

Parameters:

• moveList (list) – a list of (fromLoc,toLoc,enrichList,assemType,assemName) tuples that occurred at a single outage.

• startingAt (str) – A location label where the chain would start. This is important because the discharge moves are built when the SFP is found in a move. This method must find all assemblies in the chain leading up to this particular discharge.

• alreadyDone (list) – A list of locations that have already been tracked.

Returns:

• chain (list) – The chain as a location list in order

• enrich (list) – The axial enrichment distribution of the load assembly.

• loadName (str) – The assembly name of the load assembly

See also

repeatShufflePattern, processMoveList

processMoveList(moveList)

Processes a move list and extracts fuel management loops and charges.

Parameters:

moveList (list) –

A list of information about fuel management from a previous case. Each entry represents a move and includes the following items as a tuple:

fromLoc

the label of where the assembly was before the move

toLoc

the label of where the assembly was after the move

enrichList

a list of block enrichments for the assembly

assemType

the type of assembly that this is

movingAssemName

the name of the assembly that is moving from to

Returns:

• loadChains (list) – list of lists of location labels for each load chain (with charge/discharge). These DO NOT include special location labels like LoadQueue or SFP

• loopChains (list) – list of lists of location labels for each loop chain (no charge/discharge)

• enriches (list) – The block enrichment distribution of each load assembly

• loadChargeTypes (list) – The types of assemblies that get charged.

• loadNames (list) – The assembly names of assemblies that get brought into the core from the SFP (useful for pulling out of SFP for round 2, etc.). Will be None for anything else.

• alreadyDone (list) – All the locations that were read.

Notes

Used in the some Monte Carlo interfaces to convert ARMI moves to their format moves. Also used in repeat shuffling.

See also

makeShuffleReport

writes the file that is being processed

repeatShufflePattern

uses this to repeat shuffles

doRepeatShuffle(loadChains, loopChains, enriches, loadChargeTypes, loadNames)

Actually does the fuel movements required to repeat a shuffle order.

Parameters:

• loadChains (list) – list of lists of location labels for each load chain (with charge/discharge)

• loopChains (list) – list of lists of location labels for each loop chain (no charge/discharge)

• enriches (list) – The block enrichment distribution of each load assembly

• loadChargeTypes (list) – The types of assemblies that get charged.

• loadNames (list) – The assembly names of assemblies that get brought into the core (useful for pulling out of SFP for round 2, etc.)

See also

repeatShufflePattern

coordinates the moves for this cycle

processMoveList

builds the input lists

Notes

This is a helper function for repeatShufflePattern

workerOperate(cmd)

Handle a mpi command on the worker nodes.

prepShuffleMap()

Prepare a table of current locations for plotting shuffle maneuvers.

makeShuffleArrows()

Build data for plotting all the previous shuffles as arrows.

Returns:

arrows – Values are (currentCoords, oldCoords) tuples

Return type:

list