Main Content


Create value with unit

Since R2021b


simscape.Value lets you perform mathematical operations on values with units. A simscape.Value object binds an array of numeric values to a unit of measure and propagates this unit through mathematical operations. All members of the array must have the same unit.




V = simscape.Value() creates an empty value bound to unit 1. Values bound to the unit of 1 are called unitless.


V = simscape.Value(A) creates an array with value A bound to unit 1 (unitless).


V = simscape.Value(A,U) creates an array with value A bound to unit U.

Input Arguments

expand all

Array of numeric values, specified as a scalar, vector, or matrix. The array cannot contain complex values and cannot be sparse.

Example: 1.5

Data Types: double

Physical unit expression, specified as a character vector, nonmissing string scalar, or a scalar simscape.Unit object. The string or character vector expression can consist of valid physical unit names, numbers, math operators, such as +, -, *, /, and ^, and parentheses to specify the order of operations. Physical unit of 1 indicates a unitless simscape.Value object.

Example: 'm/s^2'

Object Functions

unitReturn unit associated with simscape.Value array
valueReturn array of numeric values converted into specified unit
convertConvert array of numeric values into different unit

You can also use core MATLAB® array functions with simscape.Value arrays. For more information, see Working with simscape.Value and simscape.Unit Objects.


collapse all

Create a value with the unit of meters:

V1 = simscape.Value(10, 'm')
V1 = 

    10 (m)

Create an array of values with the unit of centimeters:

 V2 = simscape.Value([100, 200, 300], 'cm')
V2 = 

   100   200   300


Add the two objects:

V1 + V2
ans = 

    11    12    13


You can add these objects because the units are commensurate. The return unit is m. For more information, see Computational Units.

Create a simscape.Value object in meters:

V = simscape.Value(32, 'm')
V = 

    32 (m)

Get the object value in the unit of the object:

ans =


Get the object value in centimeters:

 value(V, 'cm')
ans =


(returns a double)

Convert the object into centimeters:

 convert(V, 'cm')
ans =

    3200 (cm)

(returns a simscape.Value object)


  • Direct block parameterization is not supported, that is, you cannot use simscape.Value objects directly to specify block parameters. You can use these objects only during programmatic model construction.

  • You cannot use simscape.Value objects to specify values with units or perform unit computations in Symbolic Math Toolbox™.

  • MATLAB Coder™ does not support simscape.Value objects.

  • simscape.Value arrays do not support complex data.

  • simscape.Value arrays do not support sparse data.

  • You can use MAT-files to save and load simscape.Value objects. However, unit derivation is not saved with the units, so if a simscape.Value object is saved with a unit and loaded in a subsequent MATLAB session where some part of the unit is not defined, then MATLAB issues a warning and the object results in an invalid variable.

Version History

Introduced in R2021b

expand all