Units - Maple Programming Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Science and Engineering : Units : Verifications : Units/TestDimensions

Units

  

TestDimensions

  

verify dimensional correctness of unit expression(s)

 

Calling Sequence

Parameters

Description

Examples

Compatibility

Calling Sequence

TestDimensions(expr)

TestDimensions(expr, known, output)

Parameters

expr

-

expression or list or set of expressions

known

-

(optional) set or list of pairs to add restrictions to the possible dimensional mappings

output

-

(optional) equation of the form output = o, where o indicates what type of output is requested

Description

• 

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 LambertW, have to be dimensionless.

– 

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

• 

Equality of dimensions is verified while discarding so-called unit annotations. For example, a quantity with the dimension of 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, subexpr::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 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 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 FAIL is returned.

  

In many cases, there are some degrees of freedom for the result. For example, in an expression such as 5kg+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 length_t01,1 and the dimension for y would then have a factor length_t01,1. Similarly, there might be a factor mass1_t01,2 in one and a factor mass_t01,2 in the other. Any value assigned to these values _t01,1 and _t01,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 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 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 FAIL is returned.

– 

If you supply the optional argument output = ambiguous, and a valid mapping of subexpressions to dimensions was found, then the value true is returned if there are ambiguities in the dimensions returned for output = dimensions and 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 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 true is returned if there are ambiguities in the dimensions returned for output = dimensions(expr1, expr2, ..., exprk) and 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 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 FAIL. If, on the other hand, there is no valid mapping, then the command returns a small subset of subexpressions of 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.

Examples

Here is an example of an expression that is not valid.

UnitsTestDimensions2Unitm+3Units

false

(1)

If you load the Units package (and therefore, the Units[Simple] subpackage), then this leads to an error. This also allows use of the short form of the TestDimensions command.

withUnits

Automatically loading the Units[Simple] subpackage

AddBaseUnit,AddDimension,AddSystem,AddUnit,CommandsOnly,Converter,GetDimension,GetDimensions,GetSystem,GetSystems,GetUnit,GetUnits,HasDimension,HasSystem,HasUnit,Indets,Natural,RemoveDimension,RemoveSystem,Simple,Standard,TestDimensions,Unit,UseContexts,UseMode,UseSystem,UseUnit,UsingContexts,UsingSystem

(2)

2Unitm+3Units

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

In the following example, there is a valid assignment of dimensions to the variables - in this case the single variable, v. We ask Maple to tell us what dimension it assigns to v (and some other subexpressions).

TestDimensions2Unitm+v3Units

true

(3)

TestDimensions2Unitm+v3Units,output=dimensions

v::lengthtime,vs::length,2m+3vs::length

(4)

TestDimensions2Unitm+v3Units,output=boolean,dimensions

true,v::lengthtime,vs::length,2m+3vs::length

(5)

If we specify that v has a dimension of mass, then the expression is not valid. If Maple detects this, it can find the offending subexpressions.

TestDimensions2Unitm+v3Units,v+x,v=fy,v::Unitkg,output=boolean,contradictions

false,v::kg,2m+3vs

(6)

In some situations, there is some ambiguity in how units are assigned, for example in the expression xy+5kg if no extra information is given. In such a case, Maple will give the fully general value if you ask for output=dimensions. This output is sometimes hard to understand, but it is explained in the text above.

TestDimensionsxy+5Unitkg,output=dimensions

x::length_t282,1mass1_t282,2time_t282,3electric_current_t282,4thermodynamic_temperature_t282,5amount_of_substance_t282,6luminous_intensity_t282,7currency_t282,8amount_of_information_t282,9logarithmic_gain_t282,10,y::length_t282,1mass_t282,2time_t282,3electric_current_t282,4thermodynamic_temperature_t282,5amount_of_substance_t282,6luminous_intensity_t282,7currency_t282,8amount_of_information_t282,9logarithmic_gain_t282,10,xy::mass,xy+5kg::mass

(7)

We can also include the set of variables used in the exponents.

TestDimensionsxy+5Unitkg,output=dimensions,variables

x::length_t282,1mass1_t282,2time_t282,3electric_current_t282,4thermodynamic_temperature_t282,5amount_of_substance_t282,6luminous_intensity_t282,7currency_t282,8amount_of_information_t282,9logarithmic_gain_t282,10,y::length_t282,1mass_t282,2time_t282,3electric_current_t282,4thermodynamic_temperature_t282,5amount_of_substance_t282,6luminous_intensity_t282,7currency_t282,8amount_of_information_t282,9logarithmic_gain_t282,10,xy::mass,xy+5kg::mass,_t282,1,_t282,2,_t282,3,_t282,4,_t282,5,_t282,6,_t282,7,_t282,8,_t282,9,_t282,10

(8)

We can detect such an ambiguous case by asking for output=ambiguous.

TestDimensionsxy+5Unitkg,output=ambiguous

true

(9)

If we know that x has the dimension of mass per unit of time, then the result is unambiguous.

TestDimensionsxy+5Unitkg,x::Unitkgs,output=ambiguous

false

(10)

For output=units, in the presence of ambiguity, Maple selects one of the possible assignments of units to subexpressions.

TestDimensionsxy+5Unitkg,output=units

x::kg,y::1,xy::kg,xy+5kg::kg

(11)

We can also ask for the units for some specific subexpressions.

TestDimensionsxy+5Unitkg,output=unitsx,xy

x::kg,xy::kg

(12)

Compatibility

• 

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.

See Also

Units

Units,UseSystem

Units/Simple