Force Parameters to have descriptions

[john-science]

When constructing a Parameter object, we already have multiple checks to ensure the Parameter is valid:

armi/armi/reactor/parameters/parameterDefinitions.py

Lines 250 to 253 in 59388d2

	assert self._validName.match(name), "{} is not a valid param name".format(name)
	# nonsensical to have a serializer with no intention of saving to DB
	assert not (serializer is not None and not saveToDB)
	assert serializer is None or saveToDB

Why not add some to ensure there is a valid description field? I want to say the same for units, but many parameters are unitless, so we would have to change "unitless" to be a non-empty string.

assert description is not None and len(description)

After all, what good is a Parameter if no one can tell what it is?

[john-science]

@keckler FYI

@sombrereau @drewj-usnctech Would this be a problem for either of you?

[jakehader]

I like the idea of enforcing that these are set. Could be a breaking change, but probably a good one? Maybe we can start implementing warnings to fix before we enforce so that folks have a chance to change? I also like the idea of enforcing locations would be good too.

[drewj-usnctech]

On board for this. Parameters should have descriptions. I think setting units=None should still be supported as there are some cases where parameters really are unitless. Like number of things? It would be a small sample because the vast majority of things have units.

Maybe a non-None field like units=UNITLESS? None seems simpler tbh

[john-science]

I am changing this ticket to only FORCE Parameter descriptions, not units.

And I already have a DeprecationWarning in place:

armi/armi/reactor/parameters/parameterDefinitions.py

Lines 255 to 259 in 59388d2

	if not len(description):
	runLog.warning(
	f"DeprecationWarning: Parameter {name} defined without description.",
	single=True,
	)

The plan is:

• This version of ARMI will be released with the DeprecationWarning.
• The very next version of ARMI will change that to a hard Error.
• Then I will close this ticket.

Estimated time to close this ticket: 2 months (of waiting).

[john-science]

I have put this on the ARMI 0.4.0 Roadmap.

Really, the change in ARMI is no work at all. The time here will be spent on testing downstream projects to see if they will break.