Wolfram Function Repository

Instant-use add-on functions for the Wolfram Language

Function Repository Resource:

 UnitDimensionValidate

Source Notebook

Check whether the unit dimensions of an equation or expression are correctly balanced

Contributed by: Jason Martinez

ResourceFunction["UnitDimensionValidate"][expr]

check if the unit dimensions of expr are balanced overall and in subexpressions.

ResourceFunction["UnitDimensionValidate"][expr,property]

returns the property from the analysis of expr.

ResourceFunction["UnitDimensionValidate"][{expr1,expr2}]

checks the unit dimensions of the listed expressions are the same in addition to checking them individually.

Details and Options

UnitDimensionValidate recursively examines the subexpressions in an equation or expression, checking if each component is internally consistent with regards to unit dimensions. Where it is inconsistent, it will flag the issue either in a table or when displaying the formula with highlighting. Issues include unknown units or physical quantities, function arguments with lingering unit dimensionality, incompatible units added together or incompatible units being equated.
ResourceFunction["UnitDimensionValidate"] supports the following properties:
"DiagnosisTable"table of subexpressions and their warning or error messages
"ExpressionHighlighting"the original expression with warnings and errors highlighted
"UnitDiagnosisTable"table of subexpressions and unit dimensions for dimensional incompatibilities
"UnitDimensions"unit dimensions of the overall expression if available
"Validate"Boolean result for dimensional balance
ResourceFunction["UnitDimensionValidate"][expr] is equivalent to ResourceFunction["UnitDimensionValidate"][expr,"ExpressionHighlighting"].
Issues are categorized as errors, where unit dimensions are incompatible or can't be determined in the expression, and warnings, where unit dimension balance can be established by treating angular units and similar unit dimensions as dimensionless.
"ExpressionHighlighting" uses LightRed background highlighting for errors and Yellow background highlighting for warnings by default. See the options "CorrectHighlighting", "ErrorHighlighting" and "WarningHighlighting" to control the color and style of highlighting for different parts of the expression.
"PropertyAssociation" returns the properties "ExpressionHighlighting", "UnitDimensions" and "Validate". "Dataset" returns those properties as a Dataset. All can be used to obtain all properties besides "Dataset" and "PropertyAssociation".
"UnitDimensions" is Missing["NotAvailable"] when the expression is not dimensionally balanced.
UnitDimensionValidate supports the following options:
"CheckArgumentDimensions"Truewhether to check the arguments of functions are dimensionless
"CorrectHighlighting"AutomaticHighlighted options for correctly formatted expressions
"DimensionedArgumentFailureException"{}unit dimensions treated as dimensionless when balancing
"DimensionedArgumentWarnings"Automaticunit dimensions treated as dimensionless but highlighted when balancing
"ErrorHighlighting"AutomaticHighlighted options for erroneously formatted expressions
"WarningHighlighting"AutomaticHighlighted options for expression warnings
The default unit dimensions used by "DimensionedArgumentWarnings" include {"SolidAngleUnit","AngleUnit","RevolutionUnit","PersonUnit","ImpressionUnit",IndependentUnitDimension}.

Examples

Basic Examples (5) 

Highlight unit imbalances in an equation:

In[1]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["a", "Length"] == QuantityVariable["z", "Time"]]
Out[1]=

Added Incompatible units are flagged:

In[2]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["a", "Length"] == QuantityVariable["b", "Length"] + Quantity[2, "Seconds"]]
Out[2]=
In[3]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Distance"] Exp[(QuantityVariable["t", "ElectricPotential"] + QuantityVariable["s", "Thickness"])/ QuantityVariable["b", "Thickness"]] == QuantityVariable["z", "Thickness"]]
Out[3]=

Compare a list of expressions to ensure they all have the same unit dimensions:

In[4]:=
ResourceFunction[ "UnitDimensionValidate"][{QuantityVariable["m","Mass"]/ QuantityVariable["t","Time"], ( QuantityVariable["e","ElectricCharge"] QuantityVariable[ "E","ElectricFieldStrength"])/QuantityVariable["v","Speed"], ( QuantityVariable["e","ElectricCharge"]^2 QuantityVariable[ "E","ElectricFieldStrength"]^2 QuantityVariable["t","Time"])/( QuantityVariable["m","Mass"] QuantityVariable[ "v","Speed"]^2)}, "Validate"]
Out[4]=

Determine when a unit like an AngularUnit must be treated as dimensionless to correctly balance the expression:

In[5]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["a", "Length"] == QuantityVariable["b", "Length"]*QuantityVariable["z", "Angle"]]
Out[5]=

Use "Validate" to determine if an equation is dimensionally balanced:

In[6]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable[ "H","Height"] == (Quantity[20.6`3., "Meters"]) ((Quantity[1, 1/("Meters")]) QuantityVariable[ "D","Diameter"])^0.535`, "Validate"]
Out[6]=

Scope (8) 

Obtain a table cataloging the issues with an equation:

In[7]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Distance"] Exp[(QuantityVariable["t", "ElectricPotential"] + QuantityVariable["s", "Thickness"])/ QuantityVariable["b", "Thickness"]] == QuantityVariable["z", "Thickness"], "DiagnosisTable"]
Out[7]=

Use a table to examine the unit dimensions of the terms in an expression that is dimensionally unbalanced:

In[8]:=
ResourceFunction[ "UnitDimensionValidate"][(QuantityVariable["d", "Length"] + QuantityVariable["e", "Energy"])/QuantityVariable["t", "Time"] == QuantityVariable["v", "Speed"] + QuantityVariable["t", "Time"], "UnitBalanceDiagnosisTable"]
Out[8]=

Find the overall unit dimensions of an expression or equation:

In[9]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["V","ElectricPotential"] == QuantityVariable["I","ElectricCurrent"] QuantityVariable[ "R","ElectricResistance"], "UnitDimensions"]
Out[9]=

Obtain an Association of a dimensional analysis:

In[10]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Length"] + QuantityVariable["t", "Time"] == QuantityVariable["v", "Speed"], "PropertyAssociation"]
Out[10]=

Return the results as a Dataset:

In[11]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Length"] + QuantityVariable["t", "Time"] == QuantityVariable["v", "Speed"], "Dataset"]
Out[11]=

Return all properties in an Association:

In[12]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Length"] + QuantityVariable["t", "Time"] == QuantityVariable["v", "Speed"], All]
Out[12]=

Compare a list of expressions to ensure they all have the same unit dimensions:

In[13]:=
ResourceFunction[ "UnitDimensionValidate"][{QuantityVariable["m","Mass"]/ QuantityVariable["t","Time"], ( QuantityVariable["e","ElectricCharge"] QuantityVariable[ "E","ElectricFieldStrength"])/QuantityVariable["v","Speed"], ( QuantityVariable["e","ElectricCharge"]^2 QuantityVariable[ "E","ElectricFieldStrength"]^2 QuantityVariable["t","Time"])/( QuantityVariable["m","Mass"] QuantityVariable[ "v","Speed"]^2)}, "Validate"]
Out[13]=

UnitDimensionValidate works on differential equations:

In[14]:=
waveequation = \!\(\*SuperscriptBox[ TemplateBox[{ StyleBox["\"u\""], "\"Pressure\""}, "QuantityVariable", DisplayFunction->(TooltipBox[ StyleBox[#, FontColor -> GrayLevel[0.4], ShowStringCharacters -> False], RowBox[{"Quantity variable:", " pressure"}], TooltipStyle -> "TextStyling"]& )], TagBox[ RowBox[{"(", RowBox[{"0", ",", "2"}], ")"}], Derivative], MultilineFunction->None]\)[QuantityVariable["x","Length"], QuantityVariable["t","Time"]] == QuantityVariable["cp","Speed"]^2 \!\(\*SuperscriptBox[ TemplateBox[{ StyleBox["\"u\""], "\"Pressure\""}, "QuantityVariable", DisplayFunction->(TooltipBox[ StyleBox[#, FontColor -> GrayLevel[0.4], ShowStringCharacters -> False], RowBox[{"Quantity variable:", " pressure"}], TooltipStyle -> "TextStyling"]& )], TagBox[ RowBox[{"(", RowBox[{"2", ",", "0"}], ")"}], Derivative], MultilineFunction->None]\)[QuantityVariable["x","Length"], QuantityVariable["t","Time"]]
Out[14]=
In[15]:=
ResourceFunction["UnitDimensionValidate"][waveequation, "Validate"]
Out[15]=
In[16]:=
ResourceFunction[ "UnitDimensionValidate"][waveequation, "UnitDimensions"]
Out[16]=

Options (12) 

CorrectHighlighting (4) 

By default, dimensionally correct expressions are not highlighted:

In[17]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["a", "Length"] == QuantityVariable["b", "Length"] + QuantityVariable["v", "Speed"]*Quantity[2, "Seconds"]]
Out[17]=

Use "CorrectHighlighting" to provide a highlighting color:

In[18]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["a", "Length"] == QuantityVariable["b", "Length"] + QuantityVariable["v", "Speed"]*Quantity[2, "Seconds"], "CorrectHighlighting" -> {Background -> Green}]
Out[18]=

When there are problems with an expression, valid lower level expressions with retain their highlighting:

In[19]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["z", "Length"] == QuantityVariable["d", "Length"] + QuantityVariable["t", "Time"], "CorrectHighlighting" -> {Background -> Green}]
Out[19]=

Quantity and QuantityVariable formatting may take precedence over highlighted options:

In[20]:=
ResourceFunction["UnitDimensionValidate"][ Quantity[2, "Feet"] == QuantityVariable["b", "Length"], "CorrectHighlighting" -> {Background -> LightGray, BaseStyle -> {Red, 24}}]
Out[20]=

CheckArgumentDimensions (2) 

By default the arguments of functions are checked to ensure they are overall dimensionless:

In[21]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Distance"]/ QuantityVariable["t", "Thickness"] == Sin[QuantityVariable["v", "Feet"]], "Validate"]
Out[21]=

Set "CheckArgumentDimensions" to False to turn that off:

In[22]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Distance"]/ QuantityVariable["t", "Thickness"] == Sin[QuantityVariable["v", "Length"]], "Validate", "CheckArgumentDimensions" -> False]
Out[22]=

DimensionedArgumentFailureException (2) 

UnitDimensionValidate flags when the unit dimensions in an expression don't match when added or equated:

In[23]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Distance"]/ QuantityVariable["t", "Thickness"] == QuantityVariable["v", "Time"]]
Out[23]=

Use "DimensionedArgumentFailureExceptions" to suppress these errors for specified unit dimensions:

In[24]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Distance"]/ QuantityVariable["t", "Thickness"] == QuantityVariable["v", "Time"], "DimensionedArgumentFailureExceptions" -> {"TimeUnit"}]
Out[24]=

"DimensionedArgumentFailureExceptions" supersedes "DimensionedArgumentWarnings":

In[25]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Distance"]/ QuantityVariable["t", "Thickness"] QuantityVariable["v", "Angle"] == Sin[QuantityVariable["v", "Angle"]], "DimensionedArgumentWarnings" -> {"AngleUnit"}]
Out[25]=
In[26]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Distance"]/ QuantityVariable["t", "Thickness"] QuantityVariable["v", "Angle"] == Sin[QuantityVariable["v", "Angle"]], "DimensionedArgumentWarnings" -> {"AngleUnit"}, "DimensionedArgumentFailureExceptions" -> {"AngleUnit"}]
Out[26]=

DimensionedArgumentWarnings (2) 

UnitDimensionValidate warns when some unit dimensions like angular units must be treated as dimensionless to properly balance the expression:

In[27]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Distance"]/ QuantityVariable["t", "Thickness"] QuantityVariable["v", "Angle"] == Sin[QuantityVariable["v", "Angle"]], "DiagnosisTable"]
Out[27]=

Use "DimensionedArgumentWarnings" to control which unit dimensions receive these warnings and which then become errors:

In[28]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Distance"]/ QuantityVariable["t", "Thickness"] QuantityVariable["v", "Angle"] == Sin[QuantityVariable["v", "Angle"]], "DiagnosisTable", "DimensionedArgumentWarnings" -> {}]
Out[28]=

ErrorHighlighting (1) 

Adjust the highlighting color and formatting for errors:

In[29]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["t", "Time"] == QuantityVariable[Subscript["t", 0], "Time"] + QuantityVariable["b", "Length"]/(QuantityVariable[Subscript["v", 1], "Speed"] - QuantityVariable[Subscript["v", 2], "Time"]) - Exp[QuantityVariable["a", "Length"] - QuantityVariable["b", "Length"]/QuantityVariable["c", "Length"]], "ErrorHighlighting" -> {Background -> Red, RoundingRadius -> 25}]
Out[29]=

WarningHighlighting (1) 

Adjust the highlighting for warnings:

In[30]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["a", "Length"] == QuantityVariable["b", "Length"]*QuantityVariable["z", "Angle"], "WarningHighlighting" -> {Frame -> True, FrameStyle -> Red}]
Out[30]=

Applications (1) 

Test a variety of differential equations:

In[31]:=
(* Evaluate this cell to get the example input *) CloudGet["https://www.wolframcloud.com/obj/908f1c28-47ff-437f-afbe-68b6dfdb3e41"]
In[32]:=
AllTrue[Flatten[{odeHO, odeRC, odeLRC, grav, peq, eq, eq2, odeHO2}], ResourceFunction["UnitDimensionValidate"][#, "Validate"] &]
Out[32]=
In[33]:=
Grid[{#, ResourceFunction["UnitDimensionValidate"][#, "UnitDimensions"]} & /@ Flatten[{waveequation, odeHO, odeRC, odeLRC, grav, peq, eq, eq2, odeHO2}]]
Out[33]=

Possible Issues (2) 

Unknown units and physical quantities will also be flagged:

In[34]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable["d", "Foo"]/QuantityVariable["t", "Time"] == QuantityVariable["v", "Speed"], "PropertyAssociation"]
Out[34]=

When checking unit dimension balances, purely symbolic terms can not be resolved:

In[35]:=
ResourceFunction["UnitDimensionValidate"][ QuantityVariable[ "\[Omega]","Frequency"] QuantityVariable["x","Length"][ QuantityVariable["t","Time"]] + a Derivative[1][QuantityVariable["x","Length"]][QuantityVariable[ "t","Time"]] == A QuantityVariable["f","Speed"][QuantityVariable[ "t","Time"]], "PropertyAssociation"]
Out[35]=

Neat Examples (1) 

Test the unit balance of the regular and Hamiltonian equations of motion for every physical system entity:

In[36]:=
e = EntityList["PhysicalSystem"]; RandomSample[e, 5]
Out[37]=
In[38]:=
psformulas = DeleteCases[ Flatten[EntityValue[ e, {EntityProperty["PhysicalSystem", "EquationsOfMotion"], EntityProperty["PhysicalSystem", "HamiltonianEquationsOfMotion"]}]], _Missing]; Length[psformulas]
Out[39]=
In[40]:=
AllTrue[Flatten[Quiet[Activate[psformulas], {Cross::nonn1}]], ResourceFunction["UnitDimensionValidate"][#, "Validate"] &]
Out[40]=

Version History

  • 1.0.0 – 24 April 2026

License Information