armi Missing unit definitions

Unit definitions are missing in much of the documentation. Because there is not a single set of units used throughout ARMI, variables without unit specifications are difficult to comprehend.

It would be useful to add units on all physical quantities outlined in the documentation, preferably in a consistent manner.

Jul 28 '21 23:07 keckler

Good request, thanks. Our sphinx documentation system does auto-generate all the parameter definitions into tables with units (like this one ) based on the parameter definition code in the framework and in the plugins, which can be in places like this. However, it's true that some fraction of the parameters in there do not have units defined. Thus, we do certainly need a once-through on all the parameters included in the framework to make sure the units and definitions are clear.

Jul 29 '21 01:07 ntouran

If anyone wants to take a crack at adding units to some parameters where units are missing, I can help guide you as to what the units should be. That could be an easy first commit if you see an obvious one.

Jul 29 '21 01:07 ntouran

The scope of this issue goes beyond just parameter units alone, but should be documented in the blueprints docs too. It would be nice to be able to specify dimensions or temperatures of components on the front end as inches, cm, mm or Celsius, Fahrenheit, Kelvin and have this converted to an appropriate set of units prior to constructing the reactor.

Even with this, we should set a standard for ARMI inputs for dimensions and temperatures that the reactor model will be based on. i.e., cm and Celsius seem reasonable since that is what is already supported. Plugins should be able to transform the base units into whatever units they need and should be able to define whatever parameters they would like in those units though.

I recommend that we write a requirements document for the framework units and units management prior to making any code changes.

Jul 29 '21 02:07 jakehader

Good point about it being more than just parameters. For linear dimensions in input it's always cm. We say this in a few places but could emphasize it more if necessary.

I would argue that we should limit this issue's scope to filling in the blank/undefined units that exist but are undocumented.

Having a bigger-picture discussion about units in general should happen in the discussion forum, and that can lead to another series of simple and concrete issues for implementation, one of which should certainly be the requirements definitions

Jul 29 '21 02:07 ntouran

Hello, I am a beginner in open source and I want to contribute in it .

Jul 29 '21 11:07 Himanxu1

I searched the codebase and found the following lines that have ? units, all of which should be updated.

git grep "units=\"?\"" | xclip -selection c

armi/reactor/assemblyParameters.py:            units="?",
armi/reactor/assemblyParameters.py:        pb.defParam("Pos", units="?", description="?", location="?")
armi/reactor/assemblyParameters.py:        pb.defParam("Ring", units="?", description="?", location="?")
armi/reactor/assemblyParameters.py:        pb.defParam("THcoolantInletT", units="?", description="?", location="?")
armi/reactor/assemblyParameters.py:        pb.defParam("assemNum", units="?", description="?", location="?")
armi/reactor/assemblyParameters.py:        pb.defParam("dischargeTime", units="?", description="?", location="?")
armi/reactor/assemblyParameters.py:            units="?",
armi/reactor/assemblyParameters.py:            units="?",
armi/reactor/blockParameters.py:        pb.defParam("baseBu", units="?", description="?", saveToDB=False)
armi/reactor/blockParameters.py:        pb.defParam("basePBu", units="?", description="?", saveToDB=False)
armi/reactor/blockParameters.py:        pb.defParam("hydDiam", units="?", description="?", saveToDB=False)
armi/reactor/blockParameters.py:        pb.defParam("id", units="?", description="?", default=None)
armi/reactor/blockParameters.py:            units="?",
armi/reactor/blockParameters.py:            "avgFuelTemp", units="?", description="?", location=ParamLocation.AVERAGE
armi/reactor/blockParameters.py:            "avgTempRef", units="?", description="?", location=ParamLocation.AVERAGE
armi/reactor/blockParameters.py:        pb.defParam("bondBOL", units="?", description="?", saveToDB=False)
armi/reactor/blockParameters.py:            units="?",
armi/reactor/blockParameters.py:        pb.defParam("displacementMAG", units="?", description="?")
armi/reactor/blockParameters.py:            units="?",
armi/reactor/blockParameters.py:            units="?",
armi/reactor/blockParameters.py:            units="?",
armi/reactor/blockParameters.py:        pb.defParam("distortionReactivity", units="?", description="?")
armi/reactor/blockParameters.py:        pb.defParam("harmonic", units="?", description="?")
armi/reactor/blockParameters.py:        pb.defParam("harmonicAdj", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("holeOD", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("nHoles", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("holeOD", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("heightOuter", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("heightInner", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("base", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("height", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("inner_theta", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("outer_theta", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("inner_radius", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("outer_radius", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("height", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("azimuthal_differential", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("radius_differential", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("inner_axial", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("outer_axial", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("inner_theta", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("outer_theta", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("inner_radius", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("outer_radius", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("height", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("azimuthal_differential", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("radius_differential", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("inner_axial", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("outer_axial", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("inner_minor_radius", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("outer_minor_radius", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("major_radius", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("inner_phi", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("outer_phi", units="?", description="?")
armi/reactor/components/componentParameters.py:        pb.defParam("reference_volume", units="?", description="?")
armi/reactor/reactorParameters.py:        pb.defParam("ConvRatioCore", units="?", description="?")
armi/reactor/reactorParameters.py:        pb.defParam("absPerFisCore", units="?", description="?")
armi/reactor/reactorParameters.py:        pb.defParam("corePow", units="?", description="?")
armi/reactor/reactorParameters.py:        pb.defParam("coupledIteration", units="?", description="?", default=0)
armi/reactor/reactorParameters.py:        pb.defParam("fisFrac", units="?", description="?")
armi/reactor/reactorParameters.py:        pb.defParam("fisRateCore", units="?", description="?")
armi/reactor/reactorParameters.py:            units="?",
armi/reactor/reactorParameters.py:            units="?",
armi/reactor/reactorParameters.py:        pb.defParam("medAbsCore", units="?", description="?")
armi/reactor/reactorParameters.py:        pb.defParam("medFluxCore", units="?", description="?")
armi/reactor/reactorParameters.py:        pb.defParam("medSrcCore", units="?", description="?")
armi/reactor/reactorParameters.py:        pb.defParam("pkFlux", units="?", description="?")

Looking through, oof not all of these are abundantly obvious to a newcomer. However a meaningful contribution would be to add "cm" to all the linear dimension ones like inner_radius

On the plus side it look like only 10% of our params have units undefined in this way.

Jul 29 '21 13:07 ntouran

I also want to add that there are more units missing in the cases where simply nothing is given in the units field at all:

git grep -r "units=\"\""

armi/physics/fuelPerformance/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            "fluxAdj", units="", description="Adjoint flux"  # adjoint flux is unitless
armi/physics/neutronics/parameters.py:            units="",
armi/physics/neutronics/parameters.py:            units="",
armi/physics/thermalHydraulics/parameters.py:            units="",
armi/physics/thermalHydraulics/parameters.py:            units="",
armi/reactor/assemblyParameters.py:            "buLimit", units="", description="buLimit", default=parameters.NoDefault
armi/reactor/assemblyParameters.py:            units="",
armi/reactor/assemblyParameters.py:        pb.defParam("daysSinceLastMove", units="", description="daysSinceLastMove")
armi/reactor/assemblyParameters.py:        pb.defParam("kInf", units="", description="kInf")
armi/reactor/assemblyParameters.py:        pb.defParam("maxDpaPeak", units="", description="maxDpaPeak")
armi/reactor/assemblyParameters.py:        pb.defParam("maxPercentBu", units="", description="maxPercentBu")
armi/reactor/assemblyParameters.py:        pb.defParam("numMoves", units="", description="numMoves")
armi/reactor/assemblyParameters.py:        pb.defParam("timeToLimit", units="", description="timeToLimit", default=1e6)
armi/reactor/blockParameters.py:        pb.defParam("bu", units="", description="?")
armi/reactor/blockParameters.py:            units="",
armi/reactor/blockParameters.py:            units="",
armi/reactor/blockParameters.py:            units="",
armi/reactor/components/componentParameters.py:            units="",
armi/reactor/parameters/parameterCollections.py:            units="",
armi/reactor/reactorParameters.py:        pb.defParam("timeNode", units="", description="timeNode", default=0)
armi/reactor/reactorParameters.py:        pb.defParam("currentPercentExpanded", units="", description="")
armi/reactor/reactorParameters.py:            units="",
armi/reactor/reactorParameters.py:            "numAssembliesInSFP", units="", description="numAssembliesInSFP", default=0
armi/reactor/reactorParameters.py:        pb.defParam("numMoves", units="", description="numMoves", default=0)
armi/reactor/reactorParameters.py:        pb.defParam("timingDepletion", units="", description="timingDepletion")
armi/reactor/reactorParameters.py:        pb.defParam("timingDif3d", units="", description="timingDif3d")
armi/reactor/reactorParameters.py:        pb.defParam("timingDistribute", units="", description="timingDistribute")
armi/reactor/reactorParameters.py:        pb.defParam("timingMc2", units="", description="timingMc2")
armi/reactor/reactorParameters.py:        pb.defParam("timingSubchan", units="", description="timingSubchan")
armi/reactor/reactorParameters.py:        pb.defParam("maxcladFCCI", units="", description="", default=0.0)
armi/reactor/reactorParameters.py:            "THmaxDilationPressure", units="", description="THmaxDilationPressure"

Sometimes the fact that nothing is provided is justified by the parameter being unitless, but a quick scan through some of those results shows that many of them do in fact require units.

A related question would be if unitless parameters should be left blank, or if something like '-' should be entered to acknowledge that it is unitless, as compared to the units simply not being entered. Looking through, some unitless parameters list "None", but this is not done universally. My vote would be for at least something to be written if a parameter is unitless.

Jul 29 '21 22:07 keckler

Also see #387 for some places where units should be in method docstrings.

Aug 27 '21 16:08 keckler

I just wanted to merge both unit missing previous searches in one post by using grep regexp to match units="" and units="?". I also added grep on units="None" and units="N/A" in case these are strings for missing units (maybe it is unitless data...). I also added the file line number in the grep result.

I am also wondering if the units could be an attribute of the HDF database dataset output. This is another topic to be investigated. I think there are no units in the database file itself. I am new here so not sure.

I also listed the files to be updated below:

git grep -lnEr  "units=\"(\?*|None|N.A)\"" master | clip

master:physics/fuelPerformance/parameters.py
master:physics/neutronics/parameters.py
master:physics/thermalHydraulics/parameters.py
master:reactor/assemblyParameters.py
master:reactor/blockParameters.py
master:reactor/components/componentParameters.py
master:reactor/parameters/parameterCollections.py
master:reactor/reactorParameters.py

 git grep -nEr  "units=\"(\?*|None|N.A)\"" master | clip

master:physics/fuelPerformance/parameters.py:84:            units="",
master:physics/fuelPerformance/parameters.py:92:            units="",
master:physics/neutronics/parameters.py:40:            units="",
master:physics/neutronics/parameters.py:147:            units="",
master:physics/neutronics/parameters.py:174:            units="",
master:physics/neutronics/parameters.py:242:            units="",
master:physics/neutronics/parameters.py:254:            units="",
master:physics/neutronics/parameters.py:263:            units="",
master:physics/neutronics/parameters.py:272:            units="",
master:physics/neutronics/parameters.py:287:            units="",
master:physics/neutronics/parameters.py:296:            units="",
master:physics/neutronics/parameters.py:305:            units="",
master:physics/neutronics/parameters.py:314:            units="",
master:physics/neutronics/parameters.py:323:            units="",
master:physics/neutronics/parameters.py:332:            units="",
master:physics/neutronics/parameters.py:341:            units="",
master:physics/neutronics/parameters.py:350:            units="",
master:physics/neutronics/parameters.py:359:            units="",
master:physics/neutronics/parameters.py:368:            units="",
master:physics/neutronics/parameters.py:377:            units="",
master:physics/neutronics/parameters.py:386:            units="",
master:physics/neutronics/parameters.py:550:            "fluxAdj", units="", description="Adjoint flux"  # adjoint flux is unitless
master:physics/neutronics/parameters.py:554:            units="",
master:physics/neutronics/parameters.py:588:            units="None",
master:physics/neutronics/parameters.py:616:            units="None",
master:physics/neutronics/parameters.py:621:            "fluxPertDeltaFromDirectfluxRefWeighted", units="None", description=""
master:physics/neutronics/parameters.py:632:            units="None",
master:physics/neutronics/parameters.py:771:            units="",
master:physics/thermalHydraulics/parameters.py:38:            units="",
master:physics/thermalHydraulics/parameters.py:48:            units="",
master:reactor/assemblyParameters.py:69:            "buLimit", units="", description="buLimit", default=parameters.NoDefault
master:reactor/assemblyParameters.py:80:            units="",
master:reactor/assemblyParameters.py:115:        pb.defParam("daysSinceLastMove", units="", description="daysSinceLastMove")
master:reactor/assemblyParameters.py:117:        pb.defParam("kInf", units="", description="kInf")
master:reactor/assemblyParameters.py:119:        pb.defParam("maxDpaPeak", units="", description="maxDpaPeak")
master:reactor/assemblyParameters.py:121:        pb.defParam("maxPercentBu", units="", description="maxPercentBu")
master:reactor/assemblyParameters.py:123:        pb.defParam("numMoves", units="", description="numMoves")
master:reactor/assemblyParameters.py:125:        pb.defParam("timeToLimit", units="", description="timeToLimit", default=1e6)
master:reactor/assemblyParameters.py:264:            units="?",
master:reactor/assemblyParameters.py:273:        pb.defParam("Pos", units="?", description="?", location="?")
master:reactor/assemblyParameters.py:275:        pb.defParam("Ring", units="?", description="?", location="?")
master:reactor/assemblyParameters.py:277:        pb.defParam("THcoolantInletT", units="?", description="?", location="?")
master:reactor/assemblyParameters.py:279:        pb.defParam("assemNum", units="?", description="?", location="?")
master:reactor/assemblyParameters.py:302:        pb.defParam("dischargeTime", units="?", description="?", location="?")
master:reactor/assemblyParameters.py:313:            units="None",
master:reactor/assemblyParameters.py:339:            units="?",
master:reactor/assemblyParameters.py:348:            units="?",
master:reactor/blockParameters.py:172:            units="N/A",
master:reactor/blockParameters.py:185:            units="N/A",
master:reactor/blockParameters.py:197:        pb.defParam("bu", units="", description="?")
master:reactor/blockParameters.py:338:        pb.defParam("baseBu", units="?", description="?", saveToDB=False)
master:reactor/blockParameters.py:340:        pb.defParam("basePBu", units="?", description="?", saveToDB=False)
master:reactor/blockParameters.py:342:        pb.defParam("hydDiam", units="?", description="?", saveToDB=False)
master:reactor/blockParameters.py:360:            units="None",
master:reactor/blockParameters.py:368:            units="",
master:reactor/blockParameters.py:377:            units="",
master:reactor/blockParameters.py:384:            units="",
master:reactor/blockParameters.py:389:        pb.defParam("id", units="?", description="?", default=None)
master:reactor/blockParameters.py:433:            units="N/A",
master:reactor/blockParameters.py:441:            units="?",
master:reactor/blockParameters.py:878:            units="None",
master:reactor/blockParameters.py:889:            "avgFuelTemp", units="?", description="?", location=ParamLocation.AVERAGE
master:reactor/blockParameters.py:893:            "avgTempRef", units="?", description="?", location=ParamLocation.AVERAGE
master:reactor/blockParameters.py:918:        pb.defParam("bondBOL", units="?", description="?", saveToDB=False)
master:reactor/blockParameters.py:922:            units="None",
master:reactor/blockParameters.py:959:            units="None",
master:reactor/blockParameters.py:966:            units="?",
master:reactor/blockParameters.py:980:            units="None",
master:reactor/blockParameters.py:1094:        pb.defParam("displacementMAG", units="?", description="?")
master:reactor/blockParameters.py:1106:            units="?",
master:reactor/blockParameters.py:1113:            units="?",
master:reactor/blockParameters.py:1134:            units="None",
master:reactor/blockParameters.py:1141:            units="None",
master:reactor/blockParameters.py:1178:            units="None",
master:reactor/blockParameters.py:1185:            units="?",
master:reactor/blockParameters.py:1192:        pb.defParam("distortionReactivity", units="?", description="?")
master:reactor/blockParameters.py:1194:        pb.defParam("harmonic", units="?", description="?")
master:reactor/blockParameters.py:1196:        pb.defParam("harmonicAdj", units="?", description="?")
master:reactor/components/componentParameters.py:51:            units="",
master:reactor/components/componentParameters.py:120:            units="N/A",
master:reactor/components/componentParameters.py:159:        pb.defParam("holeOD", units="?", description="?")
master:reactor/components/componentParameters.py:161:        pb.defParam("nHoles", units="?", description="?")
master:reactor/components/componentParameters.py:171:        pb.defParam("holeOD", units="?", description="?")
master:reactor/components/componentParameters.py:227:        pb.defParam("heightOuter", units="?", description="?")
master:reactor/components/componentParameters.py:229:        pb.defParam("heightInner", units="?", description="?")
master:reactor/components/componentParameters.py:239:        pb.defParam("base", units="?", description="?")
master:reactor/components/componentParameters.py:241:        pb.defParam("height", units="?", description="?")
master:reactor/components/componentParameters.py:265:        pb.defParam("inner_theta", units="?", description="?")
master:reactor/components/componentParameters.py:267:        pb.defParam("outer_theta", units="?", description="?")
master:reactor/components/componentParameters.py:269:        pb.defParam("inner_radius", units="?", description="?")
master:reactor/components/componentParameters.py:271:        pb.defParam("outer_radius", units="?", description="?")
master:reactor/components/componentParameters.py:273:        pb.defParam("height", units="?", description="?")
master:reactor/components/componentParameters.py:275:        pb.defParam("azimuthal_differential", units="?", description="?")
master:reactor/components/componentParameters.py:277:        pb.defParam("radius_differential", units="?", description="?")
master:reactor/components/componentParameters.py:279:        pb.defParam("inner_axial", units="?", description="?")
master:reactor/components/componentParameters.py:281:        pb.defParam("outer_axial", units="?", description="?")
master:reactor/components/componentParameters.py:291:        pb.defParam("inner_theta", units="?", description="?")
master:reactor/components/componentParameters.py:293:        pb.defParam("outer_theta", units="?", description="?")
master:reactor/components/componentParameters.py:295:        pb.defParam("inner_radius", units="?", description="?")
master:reactor/components/componentParameters.py:297:        pb.defParam("outer_radius", units="?", description="?")
master:reactor/components/componentParameters.py:299:        pb.defParam("height", units="?", description="?")
master:reactor/components/componentParameters.py:301:        pb.defParam("azimuthal_differential", units="?", description="?")
master:reactor/components/componentParameters.py:303:        pb.defParam("radius_differential", units="?", description="?")
master:reactor/components/componentParameters.py:305:        pb.defParam("inner_axial", units="?", description="?")
master:reactor/components/componentParameters.py:307:        pb.defParam("outer_axial", units="?", description="?")
master:reactor/components/componentParameters.py:309:        pb.defParam("inner_minor_radius", units="?", description="?")
master:reactor/components/componentParameters.py:311:        pb.defParam("outer_minor_radius", units="?", description="?")
master:reactor/components/componentParameters.py:313:        pb.defParam("major_radius", units="?", description="?")
master:reactor/components/componentParameters.py:315:        pb.defParam("inner_phi", units="?", description="?")
master:reactor/components/componentParameters.py:317:        pb.defParam("outer_phi", units="?", description="?")
master:reactor/components/componentParameters.py:319:        pb.defParam("reference_volume", units="?", description="?")
master:reactor/parameters/parameterCollections.py:52:            units="",
master:reactor/reactorParameters.py:81:        pb.defParam("timeNode", units="", description="timeNode", default=0)
master:reactor/reactorParameters.py:163:        pb.defParam("currentPercentExpanded", units="", description="")
master:reactor/reactorParameters.py:169:        pb.defParam("numMoves", units="", description="numMoves", default=0)
master:reactor/reactorParameters.py:175:            units="N/A",
master:reactor/reactorParameters.py:245:        pb.defParam("maxcladFCCI", units="", description="", default=0.0)
master:reactor/reactorParameters.py:477:            "THmaxDilationPressure", units="", description="THmaxDilationPressure"
master:reactor/reactorParameters.py:889:            units="N/A",
master:reactor/reactorParameters.py:894:        pb.defParam("ConvRatioCore", units="?", description="?")
master:reactor/reactorParameters.py:896:        pb.defParam("absPerFisCore", units="?", description="?")
master:reactor/reactorParameters.py:905:        pb.defParam("corePow", units="?", description="?")
master:reactor/reactorParameters.py:907:        pb.defParam("coupledIteration", units="?", description="?", default=0)
master:reactor/reactorParameters.py:909:        pb.defParam("fisFrac", units="?", description="?")
master:reactor/reactorParameters.py:911:        pb.defParam("fisRateCore", units="?", description="?")
master:reactor/reactorParameters.py:923:            units="?",
master:reactor/reactorParameters.py:931:            units="?",
master:reactor/reactorParameters.py:937:        pb.defParam("medAbsCore", units="?", description="?")
master:reactor/reactorParameters.py:939:        pb.defParam("medFluxCore", units="?", description="?")
master:reactor/reactorParameters.py:941:        pb.defParam("medSrcCore", units="?", description="?")
master:reactor/reactorParameters.py:943:        pb.defParam("pkFlux", units="?", description="?")

Oct 24 '21 17:10 amargeride