Main Content

checkUnits

Check for compatible dimensions and consistent units

collapse all in page

Syntax

C = checkUnits(expr)
C = checkUnits(expr,'Compatible')
C = checkUnits(expr,'Consistent')

Description

C = checkUnits(expr) checks expr for compatible dimensions and consistent units and returns a structure containing the fields Consistent and Compatible. The fields contain logical 0 (false) or logical 1 (true) depending on the check results.

expr has compatible dimensions if all terms have the same dimensions, such as length or time. expr has consistent units if all units of the same dimension can be converted to each other with a conversion factor of 1.

example

C = checkUnits(expr,'Compatible') only checks expr for compatible dimensions.

example

C = checkUnits(expr,'Consistent') only checks expr for consistent units.

example

Examples

collapse all

Open Live Script

Check the dimensions of an equation or expression. The dimensions are checked to confirm that the equation or expression is valid.

Verify the dimensions of the equation

Ams=Bkgs

by using checkUnits with the option 'Compatible'. MATLAB® assumes that symbolic variables are dimensionless. The checkUnits function returns logical 0 (false) because the dimensions of the equation are not compatible.

u = symunit;
syms A B
eqn = A*u.m/u.s == B*u.kg/u.s;
checkUnits(eqn,'Compatible')
ans = logical
   0

Replace u.kg with u.m by using subs and repeat the check. Because the dimensions are now compatible, checkUnits returns logical 1 (true).

eqn = subs(eqn,u.kg,u.m);
checkUnits(eqn,'Compatible')
ans = logical
   1
Open Live Script

Checking units for consistency is a stronger check than compatibility. Units are consistent when all units of the same dimension can be converted to each other with a conversion factor of 1. For example, 1 Newton is consistent with 1 kg m/s² but not with 1 kg cm/s².

Show that 1 Newton is consistent with 1 kg m/s² by checking expr1 but not with 1 kg cm/s² by checking expr2.

u = symunit;
expr1 = 1*u.N + 1*u.kg*u.m/u.s^2;
expr2 = 1*u.N + 1*u.kg*u.cm/u.s^2;
checkUnits(expr1,'Consistent')
ans = logical
   1


checkUnits(expr2,'Consistent')
ans = logical
   0

Show the difference between compatibility and consistency by showing that expr2 has compatible dimensions but not consistent units.

checkUnits(expr2,'Compatible')
ans = logical
   1
Open Live Script

Check multiple equations or expressions by placing them in an array. checkUnits returns an array whose elements correspond to the elements of the input.

Check multiple equations for compatible dimensions. checkUnits returns [1 0], meaning that the first equation has compatible dimensions while the second equation does not.

u = symunit;
syms x y z
eqn1 = x*u.m == y*u.m^2/(z*u.m);
eqn2 = x*u.m + y*u.s == z*u.m;
eqns = [eqn1 eqn2];
compatible = checkUnits(eqns,'Compatible')
compatible = 1x2 logical array

   1   0
Open Live Script

Check for both compatible dimensions and consistent units of the equation or expression by using checkUnits.

Define the equations for x- and y-displacement of a moving projectile. Check their units for compatibility and consistency.

u = symunit;
syms theta x y ts
g = 9.81*u.cm/u.s^2;
v = 10*u.m/u.s;
t = ts*u.s;
x = v*cos(theta)*t;
y = v*sin(theta)*t + (-g*t^2)/2;
S = checkUnits([x y])
S = struct with fields:
    Consistent: [1 0]
    Compatible: [1 1]

The second equation has compatible dimensions but inconsistent units. This inconsistency is because g incorrectly uses cm instead of m. Redefine g and check the equations again. The second equation now has consistent units.

g = 9.81*u.m/u.s^2;
y = v*sin(theta)*t + (-g*t^2)/2;
S = checkUnits([x y])
S = struct with fields:
    Consistent: [1 1]
    Compatible: [1 1]

Input Arguments

collapse all

Input expression, specified as a symbolic expression, equation, function, vector, matrix, or multidimensional array.

Version History

Introduced in R2017a

See Also

| | | | | | |

Topics