Why does our component number density come from pseudoDensity?

[opotowsky]

There was once confusion about 2D versus 3D density, and @john-science fixed that by calling 2D density pseudoDensity (and 3D is density). But no matter how we got here, this seems like it should be 3D density:

armi/armi/reactor/components/component.py

Lines 349 to 380 in 41e169a

	def applyMaterialMassFracsToNumberDensities(self):
	"""
	Set the hot number densities for the component based on material mass fractions/density.
	Notes
	-----
	- the density returned accounts for the expansion of the component
	due to the difference in self.inputTemperatureInC and self.temperatureInC
	- After the expansion, the density of the component should reflect the 3d
	density of the material
	"""
	# note, that this is not the actual material density, but rather 2D expanded
	# `density` is 3D density
	# call getProperty to cache and improve speed
	density = self.material.getProperty("pseudoDensity", Tc=self.temperatureInC)
	self.p.numberDensities = densityTools.getNDensFromMasses(density, self.material.massFrac)
	# Sometimes material thermal expansion depends on its parent's composition (e.g. Pu frac) so
	# setting number densities can sometimes change thermal expansion behavior. Call again so
	# the material has access to its parent's comp when providing the reference initial density.
	densityBasedOnParentComposition = self.material.getProperty("pseudoDensity", Tc=self.temperatureInC)
	self.p.numberDensities = densityTools.getNDensFromMasses(
	densityBasedOnParentComposition, self.material.massFrac
	)
	# material needs to be expanded from the material's cold temp to hot,
	# not components cold temp, so we don't use mat.linearExpansionFactor or
	# component.getThermalExpansionFactor.
	# Materials don't typically define the temperature for which their references
	# density is defined so linearExpansionPercent must be called
	coldMatAxialExpansionFactor = 1.0 + self.material.linearExpansionPercent(Tc=self.temperatureInC) / 100
	self.changeNDensByFactor(1.0 / coldMatAxialExpansionFactor)

@onufer @mgjarrett @jakehader Any thoughts? Is this a massive bug?

CC @albeanth @drewejohnson

[john-science]

We had a recent conversation on this topic, and I will record it here as best I can, for posterity.

@onufer provided some history, that pseudoDensity is the 2D density we originally created to handle the expansion of materials in pin-type reactors, because the expansion was radial at the time. And axial expansion is much more expensive, and takes more math to accomplish.

@mgjarrett pointed out that pseudoDensity is just a function of linear expansion:

armi/armi/materials/material.py

Lines 460 to 471 in 88e2060

	Tk = getTk(Tc, Tk)
	dLL = self.linearExpansionPercent(Tk=Tk)
	if self.refDens is None:
	runLog.warning(
	"{0} has no reference density".format(self),
	single=True,
	label="No refD " + self.getName(),
	)
	self.refDens = 0.0
	f = (1.0 + dLL / 100.0) ** 2
	return self.refDens / f

I noted that some of our materials create hand-entered values for pseudoDensity, so they do not all follow this generic logic:

armi/armi/materials/air.py

Line 89 in 88e2060

rho_kgPerM3 = 1.15675e03 * inv_Tk**2 + 3.43413e02 * inv_Tk + 2.99731e-03

armi/armi/materials/sodium.py

Line 81 in 88e2060

critDens + f * (1 - (Tc + 273.15) / Tcrit) + g * (1 - (Tc + 273.15) / Tcrit) ** h

@keckler Points out the above pseudoDensity logic only applies for solids, not fluids. My examples were fluids.

@jakehader Argues this pseudoDensity is still needed:

Detailed axial expansion isn't free and isn't always the first modeling technique you jump to when building an initial
representation of a core.
 
Yeah you still need to do this on initialization. Note that a material's density is only used at first but then component
densities are component-informed. Once you establish a connection of a material to a component, all related "changes"
should be from the component's perspective and limited changes on the material data. I don't believe material objects
are serialized to the database.

As does @onufer :

what is being done is results in technically correct/consistent densities. this is because we add the 3rd dimension factor in
  
https://github.com/terrapower/armi/blob/41e169a945290f632b9538f4bee019604bd71f14/armi/reactor/components/component.py#L374-L380
 
note that i did a fairly detailed auidit of this back in 2022. see these PRs. we do have good tests showing that it behaves correctly

- https://github.com/terrapower/armi/pull/818
- https://github.com/terrapower/armi/pull/841
- https://github.com/terrapower/armi/pull/860

I believe the conversation here (for solids, anyway) is fairly definitive. Though, this still leaves two questions:

1. What is the correct behavior we want for fluids?
2. Where is the best place in ARMI to document this?

[keckler]

The correct behavior for fluids is that their linearExpansion should be zero. If implemented correctly, this should imply that density and pseudoDensity return the same things.

This is confusing because in real life, fluids DO have linear expansion coefficients.

This is what ARMI needs, however, because ARMI uses linearExpansion for determining the dimensions of components (and for fluids in an open container like a Block, their dimensions are not impacted by their expansion, just their masses). ARMI then uses the density and/or pseudoDensity to adjust the masses. For a solid material, the mass and dimensions need to be exactly in sync. For a liquid, the dimensions should not change with temperature, but the mass should.

[albeanth]

I haven't fully digested this discussion, but this is related, I believe --> #1824.

While I agree that it is important to allow users to not always perform axial expansion for pin-type reactors, the concept of a "pseudo" or "2D density" is rather odd and is a TerraPower specific "thing" that is rather unintuitive, in my opinion. I think that we could make this better. E.g., following the changes discussed in #1824 and possibly pulling the trigger on making everything thermal expansion a formal open-source plugin, as @keckler has long advocated for. This would better allow users control over enabling axial and/or radial expansion for their uses (whether that be simply enabling/disabling or even creating subclasses for specific behavior for unique designs/applications).

[john-science]

@keckler I'm interested. What would this look like?

[keckler]

@keckler I'm interested. What would this look like?

This would look like a lot of work.

:-)

I think it would require a very, very large change to some deeply-embedded parts of ARMI. For instance, all of our components have this idea of being able to grab them off the data model at their hot or cold temperatures. And we incorporate this concept of hot/cold dimensions into the blueprints file natively. When building a reactor from blueprints, it is expanded to "hot" temperatures very early on in the process (in fact, we expand the blueprints in memory, which means we are pretty committed to this idea). Also the way that materials are expected to be used is based on the ARMI-specific paradigms for thermal expansion, which, as we've seen, is confusing. Fundamentally, ARMI was built from the start with the idea that thermal expansion (in the radial direction only!) is something that cannot be ignored, So it would take a lot of effort to remove that deep assumption.

Ultimately, though, thermal expansion (solid mechanics, really) is physics just like any other. It has different importance to different people, and for that reason it would be best suited as a plugin. ARMI should not be baking specific assumptions and modeling paradigms around solid mechanics into the framework. Personally, I think this has caused us a lot of headaches. A plugin that only does thermal expansion, and that lives in the interface stack like any other, seems like a completely reasonable thing.

[john-science]

That's interesting. A PinTypeReactorThermalExpander interface, maybe?

That's a big change, for sure. I'm not sure it's huge though. It's mostly code refactoring, which I don't find particularly time-consuming or stressful.

[albeanth]

Ultimately, though, thermal expansion (solid mechanics, really) is physics just like any other. It has different importance to different people, and for that reason it would be best suited as a plugin. ARMI should not be baking specific assumptions and modeling paradigms around solid mechanics into the framework. Personally, I think this has caused us a lot of headaches. A plugin that only does thermal expansion, and that lives in the interface stack like any other, seems like a completely reasonable thing.

Agreed with all of this. It is 100% physics, should be treated as such, and absolutely not baked so hard into ARMI as it currently is. The only exception being having thermal expansion being an interface in the interface stack. Since thermal expansion is SO embedded into different things, it almost feels like it should be more of a "utility" that has an API that can be used instead of an interface in the stack. Admittedly, this is a major anti-pattern from the rest of the framework, but could be considered, I think.

A PinTypeReactorThermalExpander interface, maybe?

Not sure if a "pin-specific" interface is necessary. Linear thermal expansion, like we do in ARMI, at its most fundamental level is geometry agnostic. There might be reason for it though!