simscape.Value

Create value with unit

Since R2021b

Description

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.

Creation

Syntax

V = simscape.Value()

V = simscape.Value(A)

V = simscape.Value(A,U)

Description

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

A — Array of numeric values

scalar | vector | matrix

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

U — Physical unit expression

character vector | nonmissing string scalar | scalar simscape.Unit object

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

unit	Return unit associated with simscape.Value array
value	Return array of numeric values converted into specified unit
convert	Convert 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.

Examples

Create and Manipulate Values with Units

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

    (cm)

Add the two objects:

V1 + V2

ans = 

    11    12    13

    (m)

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

Convert Values into Different 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:

 value(V)

ans =

    32

Get the object value in centimeters:

 value(V, 'cm')

ans =

    3200

(returns a double)

Convert the object into centimeters:

 convert(V, 'cm')

ans =

    3200 (cm)

(returns a simscape.Value object)

Limitations

• 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

R2024a: Compact display of simscape.Value and simscape.Unit objects

When you place simscape.Value and simscape.Unit objects in table, cell, or structure arrays, or in MATLAB classes, the Command Window displays their values and units explicitly if they fit into the available width of the Command Window. For row vectors greater than maximum width, empty vectors, and for single line display of matrices and row vectors, you can still see only the object member dimensions and type.

In previous releases, the value and unit in a simscape.Value object were separated by a colon. Now, the unit is shown in parentheses after the value.