How can we improve Block.getNumPins?

[drewj-tp]

tl;dr what is a pin even?

getNumBlocks

armi/armi/reactor/blocks.py

Lines 1066 to 1079 in 59c392c

	nPins = [
	sum(
	[
	(
	int(c.getDimension("mult"))
	if isinstance(c, basicShapes.Circle)
	else 0
	)
	for c in self.iterComponents(compType)
	]
	)
	for compType in PIN_COMPONENTS
	]
	return 0 if not nPins else max(nPins)

does what it says it does

1. Sums the multiplicities of things with one of a pre-specified Flags.
2. Creates a list of those summed multiplicities for all the specified.
3. If any are found, returns the maximum of that list. Otherwise, returns zero.

However, there are some small edge cases that tripped me up that I'll present with this example based off the MHTGR input (#224)

mhtgr_get_pins.py

import armi
from armi.reactor.blocks import HexBlock
from armi.reactor.components import Circle
from armi.reactor.flags import Flags

armi.configure()

N_BP_PINS = 6
N_SMALL_COOLANT_PINS = 6
N_LARGE_COOLANT_PINS = 43
# Cound fuel + coolant pins per half of the hexagon
N_COOLANT_PINS = (N_LARGE_COOLANT_PINS + N_SMALL_COOLANT_PINS) * 2
# Might be of by a few by it's still much more than coolant pins
N_FUEL_PINS = 105 * 2
TOTAL_PINS = N_BP_PINS + N_COOLANT_PINS + N_FUEL_PINS

# Component size nor properties are really important here, just that we have
# unique components with some relevant flags and multiplicity
compKwargs = {
    "Thot": 20,
    "Tinput": 20,
    "id": 0.0,
    "od": 1.0,
}

block = HexBlock("mhtgr350")
fuel = Circle(name="fuel", material="UO2", mult=N_FUEL_PINS, **compKwargs)
fuel.p.flags = Flags.FUEL | Flags.DEPLETABLE
block.add(fuel)

poison = Circle(name="poison", material="B4C", mult=N_BP_PINS, **compKwargs)
poison.p.flags = Flags.POISON | Flags.DEPLETABLE
block.add(poison)

# Very wrong material but it's here
coolant = Circle(name="coolant", material="Sodium", mult=N_COOLANT_PINS, **compKwargs)
coolant.p.flags = Flags.COOLANT
block.add(coolant)


def check(b: HexBlock):
    nPins = b.getNumPins()
    if nPins != TOTAL_PINS:
        print(f"  {nPins=} != {TOTAL_PINS=}")
    else:
        print("  Okay!")


print("None with pin flag")
check(block)  # hits error condition

print("All with pin flag")
for c in [fuel, coolant, poison]:
    c.p.flags |= Flags.PIN
check(block)  # now we're good

For the first go, none of the pins have the Flags.PIN flag. Partially because this was new to me as of today. But also, because I cannot find any examples of this flag being in any blueprint file in any repository I can access. Not to say the magic auto-assignment of flags doesn't pick that up. It's just not something I'd seen before.

Without Flags.PIN, getNumPins returns 210 pins. There are 210 things with the fuel flag (one comp with multiplicity of 210) and that is the largest number in the list of "multiplicities of circles with a certain flag." This does not equal the number of "lattice sites with circular objects" that I may consider to be pins.

Adding the Flags.PIN to every component and getNumPins returns 314, or what I put down as the expected number of pins (fuel + burnable poison + coolant) from the start.

Problems?

If you only have one type of thing on your hexagonal lattice, and it has one of the special flags, you're fine. But, as soon as you have mixed things, this could break down. Or if you always include pin in the flags portion of a component definition for things you'd like to be flags, you're also good.

We use getNumPins to determine Block.p.pinLocation

armi/armi/reactor/blocks.py

Line 1939 in 59c392c

self.p.pinLocation = list(range(1, nPins + 1))

If this count is wrong, pinLocation vector is going to have the wrong number of elements. Since pinLocation reflects the ARMI-numbering of where that pin is in space, solvers that use pinLocation to place data like pinPowByPin in 2d space will incorrectly place data.

What to do?

Some thoughts on how we could improve this.

What is a pin? Do fluids count?

This was a choice I made in the model above: the coolant channel in the mhtgr example is a pin. Flags.COOLANT is not listed in the magic list of flags that could be a pin

armi/armi/reactor/blocks.py

Lines 53 to 61 in 59c392c

	PIN_COMPONENTS = [
	Flags.CONTROL,
	Flags.PLENUM,
	Flags.SHIELD,
	Flags.FUEL,
	Flags.CLAD,
	Flags.PIN,
	Flags.WIRE,
	]

But neither is Flags.POISON. A burnable poison compact has a much stronger argument for being a pin than coolant. Same for (imho) a shield component.

More advanced logic

Circles should be pins. That makes sense. Could we look at the dimensionality of the circles and see if any have coincident inner and outer diameters? Then fuel + clad would align and be one pin. But how would you capture two different materials surrounded by the same sized cladding cylinder?

Spatial grid

If a HexBlock has a hexagonal spatial grid attached to it, it seems like a straightforward argument to look at all the things that live on that spatial grid. Maybe that have one of the pre-determined flags. But that feels more explicit

Related

• getNumPins() misinterprets some non-pinned blocks as having pins #1096
• Improve logic for getNumPins #1098
• Update logic in block.getNumPins #1222
• Misleading Method Name (opinions wanted)  #1753 (comment)

[drewj-tp]

Some thoughts in #1896 (reply in thread) about Block.pin accessor handing the pin-like work

[john-science]

If "what even is a pin" becomes a real question, I think we need to fall back to adding a Flags.PIN to every pin.

And I think we need to change getNumPins() to have a flag for:

• Get all real, physical pins
• Get all pins plus the number of missing pins if there are holes missing in the regular, geometric pattern you would expect the pins to be in

[drewj-tp]

If you load the C5G7 test reactor and grab an assembly, you get a hilariously large number of pins

>>> r = armi.init(fName="armi/tests/c5g7/c5g7-settings.yaml").r
>>> fuelBlock = r.core[0][0]
>>> fuelBlock.getNumPins()
528

In that model, there are two clad components per lattice site

armi/armi/tests/c5g7/c5g7-blueprints.yaml

Lines 86 to 114 in c6f46e5

	zirconium clad: &clad_Zr
	shape: Circle
	material: Custom
	isotopics: Zr clad
	Tinput: 20.0
	Thot: 20.0
	id: .8360
	od: .9500
	latticeIDs: [U]
	gap 2: &fuel_gap_2
	shape: Circle
	material: Void
	Tinput: 20.0
	Thot: 20.0
	id: zirconium clad.od
	od: aluminum clad.id
	latticeIDs: [U]
	aluminum clad: &clad_Al
	# NEA/NSC/DOC(96)2 Documents:
	# "This clad is used to simulate hot conditions at room temperature
	# (decrease the moderation ratio)"
	shape: Circle
	material: Custom
	isotopics: Al clad
	Tinput: 20.0
	Thot: 20.0
	id: .9700
	od: 1.0800
	latticeIDs: [U]

So you double count the sites. There are 17x17 total lattice sites, some of which are empty, so the upper bound on "real" pins is 289

[drewj-tp]

Potential solution that came out of a chat w/ @john-science: What if we made a Pin(Composite) subclass that could live on a Block and contained concentric Circle components? This is kind of in the same vein as

• ARMI should have more abstract classes #1896
• Provide a Compact class to hold particle fuel and matrix #1134

That allows us to provide an answer to the question of "what is a pin, even?"

Getting thoughts out of my head real quick:

• Definable in blueprints in separate group section?
• Live on lattice sites like other components
• What is going to break if we add non-component children to a block?