The TestDimensions command verifies dimensional correctness of one or more expressions with units. By default, it returns true if there is a valid assignment of dimensions to all subexpressions of expr that is consistent with any of the mappings specified in the optional argument known, and false otherwise. Validity is tested for all subexpressions occurring in expr.

This command underlies the Simple Units environment, provided by the Units[Simple] subpackage. Every command in Units[Simple] that needs to determine whether an expression is valid or not, does so using the TestDimensions command.

The following rules apply:

All operands of sums, equations, inequations, and inequalities have to have the same dimension.

The outcome of a sum has the same dimension as all of its arguments.

The outcome of a product has the product of the dimensions of its arguments.

If an expression is raised to a rational power, the outcome has the dimension of the base raised to that same power.

If an expression is raised to a power that's not a rational constant, then the base and exponent need to be dimensionless and the outcome is also dimensionless.

The two operands of the two-argument $\arctan$ function have to have the same dimension.

All operands of other mathematical functions defined in Maple, such as $\exp$ or $\ln$ or $\mathrm{LambertW}$, have to be dimensionless.

The outcomes of other mathematical functions defined in Maple, such as $\exp$ or $\ln$ or $\mathrm{LambertW}$, have to be dimensionless.

Equality of dimensions is verified while discarding so-called unit annotations. For example, a quantity with the dimension of $\mathrm{plane\_angle}$ has the same dimension as unitless constants.

The argument expr can be any Maple expression or collection of expressions, represented as a set, a list, an rtable, or generally any container for which the indets command examines the entries. It cannot be an expression sequence (except of length 1).

The argument known is a set or list of pairs subexpr :: Unit(some_unit), or equivalently, $\mathrm{subexpr}::⟦\mathrm{some\_unit}⟧$. This can be used to enforce known dimensionalities of particular subexpressions.

By default, TestDimensions returns only true or false, to indicate whether it found a valid mapping of subexpressions to dimensions. You can select other types of output with the output option:

If you supply the optional argument output = boolean, you get the default output.

If you supply the optional argument output = units and a valid mapping of subexpressions to dimensions exists, the command will instead return a set of mappings of the form subexpr :: Unit(some_unit), where some_unit is a unit of a suitable dimension. If no valid mapping could be found, the value $\mathrm{FAIL}$ is returned.

If you supply an optional argument of the form output = units(expr1, expr2, ..., exprk) and a valid mapping of subexpressions to dimensions exists, the command will instead return a set of mappings of the form norm_expr :: Unit(some_unit), where norm_expr is one of expr1, expr2, ..., exprk, normalized using a custom version of primpart, and where some_unit is a unit of a suitable dimension. Any expressions in expr1, expr2, ..., exprk that were not encountered are omitted from the result. If no valid mapping could be found, the value $\mathrm{FAIL}$ is returned.

If you supply the optional argument output = dimensions and a valid mapping of subexpressions to dimensions exists, the command will instead return a set of mappings of the form subexpr :: some_dimension, where some_dimension is a valid product of base dimensions for subexpr, as the command convert/dimensions might return. If no valid mapping could be found, the value $\mathrm{FAIL}$ is returned.

In many cases, there are some degrees of freedom for the result. For example, in an expression such as $5⟦\mathrm{kg}⟧+xy$, the variable $x$ can have any arbitrary dimension, as long as the dimension of $y$ is such that $xy$ has the dimension mass. This is indicated by specifying, for example, the dimension of $x$ as a product of base dimensions raised to symbolic powers. In the previous example, for example, the dimension for $x$ may have a factor ${\mathrm{length}}^{{\mathrm{\_t0}}_{1,1}}$ and the dimension for $y$ would then have a factor ${\mathrm{length}}^{-{\mathrm{\_t0}}_{1,1}}$. Similarly, there might be a factor ${\mathrm{mass}}^{1-{\mathrm{\_t0}}_{1,2}}$ in one and a factor ${\mathrm{mass}}^{{\mathrm{\_t0}}_{1,2}}$ in the other. Any value assigned to these values ${\mathrm{\_t0}}_{1,1}$ and ${\mathrm{\_t0}}_{1,2}$ will lead to a valid dimension for $x$ and $y$.

If you supply an optional argument of the form output = dimensions(expr1, expr2, ..., exprk) and a valid mapping of subexpressions to dimensions exists, the command will instead return a set of mappings of the form norm_expr :: some_dimension, where norm_expr is one of expr1, expr2, ..., exprk, normalized using a custom version of primpart, and where some_dimension is a dimension, possibly including variable exponents as with output = dimensions. Any expressions in expr1, expr2, ..., exprk that were not encountered are omitted from the result. If no valid mapping could be found, the value $\mathrm{FAIL}$ is returned.

If you supply the optional argument output = variables, and a valid mapping of subexpressions to dimensions exists, the command will instead return the set of variables occurring in the exponents that would be returned with the argument output = dimensions. This output is mostly useful for programs analyzing the dimensional consistency of expressions, not so much for users entering the command manually. If no valid mapping could be found, the value $\mathrm{FAIL}$ is returned.

If you supply the optional argument output = variables(expr1, expr2, ..., exprk) and a valid mapping of subexpressions to dimensions exists, the command will instead return the set of variables occurring in the exponents that would be returned with the argument output = dimensions(expr1, expr2, ..., exprk). That is, this is like output = variables, but restricted to the subexpressions expr1, expr2, ..., exprk. If no valid mapping could be found, the value $\mathrm{FAIL}$ is returned.

If you supply the optional argument output = ambiguous, and a valid mapping of subexpressions to dimensions was found, then the value $\mathrm{true}$ is returned if there are ambiguities in the dimensions returned for output = dimensions and $\mathrm{false}$ if there are no ambiguities. There are ambiguities exactly if the result for output = variables is a nonempty set. If no valid mapping of subexpressions to dimensions was found, then the value $\mathrm{FAIL}$ is returned.

If you supply the optional argument output = ambiguous(expr1, expr2, ..., exprk) and a valid mapping of subexpressions to dimensions was found, then the value $\mathrm{true}$ is returned if there are ambiguities in the dimensions returned for output = dimensions(expr1, expr2, ..., exprk) and $\mathrm{false}$ if there are no ambiguities. There are ambiguities exactly if the result for output = variables(expr1, expr2, ..., exprk) is a nonempty set. If no valid mapping of subexpressions to dimensions was found, then the value $\mathrm{FAIL}$ is returned.

If you supply the optional argument output = contradictions, and a valid mapping of subexpressions to dimensions exists, the command will instead return the value $\mathrm{FAIL}$. If, on the other hand, there is no valid mapping, then the command returns a small subset of subexpressions of $\mathrm{expr}$ or entries of known so that those expressions cannot be given suitable dimensions simultaneously.

If you supply an option of the form output = o, where o is a list of (some of) the values described above, the command will return a sequence of the corresponding output values.

$\mathrm{Units}\left[\mathrm{TestDimensions}\right]\left(2\mathrm{Unit}\left(m\right)+3\mathrm{Unit}\left(s\right)\right)$

$\mathrm{false}$

$\mathrm{with}\left(\mathrm{Units}\right)$

Automatically loading the Units[Simple] subpackage

$\left[\mathrm{AddBaseUnit}\,\mathrm{AddDimension}\,\mathrm{AddSystem}\,\mathrm{AddUnit}\,\mathrm{CommandsOnly}\,\mathrm{Converter}\,\mathrm{GetDimension}\,\mathrm{GetDimensions}\,\mathrm{GetSystem}\,\mathrm{GetSystems}\,\mathrm{GetUnit}\,\mathrm{GetUnits}\,\mathrm{HasDimension}\,\mathrm{HasSystem}\,\mathrm{HasUnit}\,\mathrm{Indets}\,\mathrm{Natural}\,\mathrm{RemoveDimension}\,\mathrm{RemoveSystem}\,\mathrm{Simple}\,\mathrm{Split}\,\mathrm{Standard}\,\mathrm{TestDimensions}\,\mathrm{Unit}\,\mathrm{UseContexts}\,\mathrm{UseMode}\,\mathrm{UseSystem}\,\mathrm{UseUnit}\,\mathrm{UsingContexts}\,\mathrm{UsingSystem}\right]$

$2\mathrm{Unit}\left(m\right)+3\mathrm{Unit}\left(s\right)$

Error, (in Units:-Simple:-`+`) the following expressions imply incompatible dimensions: 2*Units:-Unit(m)+3*Units:-Unit(s)

$\mathrm{TestDimensions}\left(2\mathrm{Unit}\left(m\right)+v\cdot 3\mathrm{Unit}\left(s\right)\right)$

$\mathrm{true}$

$\mathrm{TestDimensions}\left(2\mathrm{Unit}\left(m\right)+v\cdot 3\mathrm{Unit}\left(s\right)\,'\mathrm{output}'='\mathrm{dimensions}'\right)$

$\left\{v::\left(\frac{\mathrm{length}}{\mathrm{time}}\right)\,\left(v⟦s⟧\right)::\mathrm{length}\,\left(2⟦m⟧+3v⟦s⟧\right)::\mathrm{length}\right\}$

$\mathrm{TestDimensions}\left(2\mathrm{Unit}\left(m\right)+v\cdot 3\mathrm{Unit}\left(s\right)\,'\mathrm{output}'=\left['\mathrm{boolean}'\,'\mathrm{dimensions}'\right]\right)$

$\mathrm{true},\left\{v::\left(\frac{\mathrm{length}}{\mathrm{time}}\right)\,\left(v⟦s⟧\right)::\mathrm{length}\,\left(2⟦m⟧+3v⟦s⟧\right)::\mathrm{length}\right\}$

$\mathrm{TestDimensions}\left(\left[2\mathrm{Unit}\left(m\right)+v\cdot 3\mathrm{Unit}\left(s\right)\,v+x\,v=f\left(y\right)\right]\,\left\{v::\mathrm{Unit}\left(\mathrm{kg}\right)\right\}\,'\mathrm{output}'=\left['\mathrm{boolean}'\,'\mathrm{contradictions}'\right]\right)$

$\mathrm{false},\left\{v::⟦\mathrm{kg}⟧\,2⟦m⟧+3v⟦s⟧\right\}$

$\mathrm{TestDimensions}\left(xy+5\mathrm{Unit}\left(\mathrm{kg}\right)\,\mathrm{output}=\mathrm{dimensions}\right)$

$\left\{x::\left({\mathrm{length}}^{-{\mathrm{variable}}_{1,1}}{\mathrm{mass}}^{1-{\mathrm{variable}}_{1,2}}{\mathrm{time}}^{-{\mathrm{variable}}_{1,3}}{\mathrm{electric\_current}}^{-{\mathrm{variable}}_{1,4}}{\mathrm{thermodynamic\_temperature}}^{-{\mathrm{variable}}_{1,5}}{\mathrm{amount\_of\_substance}}^{-{\mathrm{variable}}_{1,6}}{\mathrm{luminous\_intensity}}^{-{\mathrm{variable}}_{1,7}}{\mathrm{currency}}^{-{\mathrm{variable}}_{1,8}}{\mathrm{amount\_of\_information}}^{-{\mathrm{variable}}_{1,9}}{\mathrm{logarithmic\_gain}}^{-{\mathrm{variable}}_{1,10}}\right)\,y::\left({\mathrm{length}}^{{\mathrm{variable}}_{1,1}}{\mathrm{mass}}^{{\mathrm{variable}}_{1,2}}{\mathrm{time}}^{{\mathrm{variable}}_{1,3}}{\mathrm{electric\_current}}^{{\mathrm{variable}}_{1,4}}{\mathrm{thermodynamic\_temperature}}^{{\mathrm{variable}}_{1,5}}{\mathrm{amount\_of\_substance}}^{{\mathrm{variable}}_{1,6}}{\mathrm{luminous\_intensity}}^{{\mathrm{variable}}_{1,7}}{\mathrm{currency}}^{{\mathrm{variable}}_{1,8}}{\mathrm{amount\_of\_information}}^{{\mathrm{variable}}_{1,9}}{\mathrm{logarithmic\_gain}}^{{\mathrm{variable}}_{1,10}}\right)\,\left(xy\right)::\mathrm{mass}\,\left(xy+5⟦\mathrm{kg}⟧\right)::\mathrm{mass}\right\}$

$\mathrm{TestDimensions}\left(xy+5\mathrm{Unit}\left(\mathrm{kg}\right)\,\mathrm{output}=\left[\mathrm{dimensions}\,\mathrm{variables}\right]\right)$

$\left\{x::\left({\mathrm{length}}^{-{\mathrm{variable}}_{1,1}}{\mathrm{mass}}^{1-{\mathrm{variable}}_{1,2}}{\mathrm{time}}^{-{\mathrm{variable}}_{1,3}}{\mathrm{electric\_current}}^{-{\mathrm{variable}}_{1,4}}{\mathrm{thermodynamic\_temperature}}^{-{\mathrm{variable}}_{1,5}}{\mathrm{amount\_of\_substance}}^{-{\mathrm{variable}}_{1,6}}{\mathrm{luminous\_intensity}}^{-{\mathrm{variable}}_{1,7}}{\mathrm{currency}}^{-{\mathrm{variable}}_{1,8}}{\mathrm{amount\_of\_information}}^{-{\mathrm{variable}}_{1,9}}{\mathrm{logarithmic\_gain}}^{-{\mathrm{variable}}_{1,10}}\right)\,y::\left({\mathrm{length}}^{{\mathrm{variable}}_{1,1}}{\mathrm{mass}}^{{\mathrm{variable}}_{1,2}}{\mathrm{time}}^{{\mathrm{variable}}_{1,3}}{\mathrm{electric\_current}}^{{\mathrm{variable}}_{1,4}}{\mathrm{thermodynamic\_temperature}}^{{\mathrm{variable}}_{1,5}}{\mathrm{amount\_of\_substance}}^{{\mathrm{variable}}_{1,6}}{\mathrm{luminous\_intensity}}^{{\mathrm{variable}}_{1,7}}{\mathrm{currency}}^{{\mathrm{variable}}_{1,8}}{\mathrm{amount\_of\_information}}^{{\mathrm{variable}}_{1,9}}{\mathrm{logarithmic\_gain}}^{{\mathrm{variable}}_{1,10}}\right)\,\left(xy\right)::\mathrm{mass}\,\left(xy+5⟦\mathrm{kg}⟧\right)::\mathrm{mass}\right\},\left\{{\mathrm{variable}}_{1,1}\,{\mathrm{variable}}_{1,2}\,{\mathrm{variable}}_{1,3}\,{\mathrm{variable}}_{1,4}\,{\mathrm{variable}}_{1,5}\,{\mathrm{variable}}_{1,6}\,{\mathrm{variable}}_{1,7}\,{\mathrm{variable}}_{1,8}\,{\mathrm{variable}}_{1,9}\,{\mathrm{variable}}_{1,10}\right\}$

$\mathrm{TestDimensions}\left(xy+5\mathrm{Unit}\left(\mathrm{kg}\right)\,\mathrm{output}=\mathrm{ambiguous}\right)$

$\mathrm{true}$

$\mathrm{TestDimensions}\left(xy+5\mathrm{Unit}\left(\mathrm{kg}\right)\,\left\{x::\left(\mathrm{Unit}\left(\frac{\mathrm{kg}}{s}\right)\right)\right\}\,\mathrm{output}=\mathrm{ambiguous}\right)$

$\mathrm{false}$

$\mathrm{TestDimensions}\left(xy+5\mathrm{Unit}\left(\mathrm{kg}\right)\,\mathrm{output}=\mathrm{units}\right)$

$\left\{x::⟦\mathrm{kg}⟧\,y::1\,\left(xy\right)::⟦\mathrm{kg}⟧\,\left(xy+5⟦\mathrm{kg}⟧\right)::⟦\mathrm{kg}⟧\right\}$

$\mathrm{TestDimensions}\left(xy+5\mathrm{Unit}\left(\mathrm{kg}\right)\,\mathrm{output}=\mathrm{units}\left(x\,xy\right)\right)$

$\left\{x::⟦\mathrm{kg}⟧\,\left(xy\right)::⟦\mathrm{kg}⟧\right\}$

The Units[TestDimensions] command was introduced in Maple 2017.

For more information on Maple 2017 changes, see Updates in Maple 2017.

The Units[TestDimensions] command was updated in Maple 2018.

The output option was updated in Maple 2018.