Main Content

simscape.mustBeCommensurateUnit

Validate that units are commensurate

Since R2021b

collapse all in page

Syntax

simscape.mustBeCommensurateUnit(unitlist)

Description

simscape.mustBeCommensurateUnit(unitlist) throws an error if all the units in the list are not positive. This function does not return a value. The error message reports the unit associated with the first argument in the list and the first unit that is not commensurate with this unit.

simscape.mustBeCommensurateUnit calls the ... function to determine if the units are commensurate.

example

Examples

collapse all

Create a simscape.Value object:

 v1 = simscape.Value([100, 200, 300], "cm/s");

Create scalar simscape.Unit objects: 

u1 = simscape.Unit("mm/s");
u2 = simscape.Unit("rad/s");

Validate that units of the three objects are commensurate with the unit of meters per second:

 simscape.mustBeCommensurateUnit(v1,u1,u2,"m/s")
Unit 'cm/s' is not commensurate with 'rad/s'.

The error message reports the unit associated with the first argument, v1 (cm/s), and then the first unit in the rest of the list that is not commensurate with cm/s (rad/s).

This function calculates the area of a rectangle:

 function a = area(length, width)
  arguments
    length (1, 1) simscape.Value {simscape.mustBeCommensurateUnit(length, 'm')}
    width  (1, 1) simscape.Value {simscape.mustBeCommensurateUnit(width, 'm')}
  end
  a = length * width;
end

Call the function using two simscape.Value objects as arguments: 

v1 = simscape.Value(10, "cm");
v2 = simscape.Value(1, "kg");
area(v1,v2)
Error using area (line 4)
 area(v1,v2)
          ↑
Invalid argument at position 2. Unit 'kg' is not commensurate with 'm'.

The error message reports the invalid argument position, its associated unit (kg), and the expected commensurate unit (m).

Input Arguments

collapse all

List of units for comparison, specified as character vectors, strings, scalar simscape.Unit objects, or simscape.Value objects. For simscape.Value objects, the function compares the unit of the object with the other units in the list.

Tips

  • simscape.mustBeCommensurateUnit is designed to be used for function argument validation.

Version History

Introduced in R2021b

See Also

|

Topics