Main Content

Working with simscape.Value and simscape.Unit Objects

In physical modeling, block parameters, variables, and physical signals are represented as a value with associated unit. Simscape™ unit manager automatically performs the necessary unit conversion operations when solving a physical network. simscape.Value and simscape.Unit objects essentially implement a MATLAB® interface that replicates the unit manager functionality outside of Simscape:

  • simscape.Value binds arrays of arithmetic values to units and propagates those units through mathematical operations. All members of an array must have the same unit.

  • simscape.Unit represents units of measure without an associated value, and therefore lets you write MATLAB functions that emulate the unit propagation behavior.

Use simscape.Value and simscape.Unit to:

  • Preprocess or postprocess simulation data with units in MATLAB, for example, calculate total fluid mass or plot vehicle dynamics.

  • Create value with unit objects in MATLAB and manipulate them during programmatic model construction.

  • Write MATLAB functions that operate on values with units.

For example, this function computes page-wise matrix multiplication while propagating units:

function out = mypagemtimes(a, b)
  out = simscape.Value(pagemtimes(value(a),value(b)),unit(a)*unit(b));
end

The function:

  • Takes two simscape.Value objects, a and b, as arguments.

  • Extracts values from a and b.

  • Uses the MATLAB pagemtimes function on these extracted values.

  • Uses the simscape.Unit objects to compute the derived unit.

  • Reattaches the new unit to the computed array of values and returns the resulting simscape.Value object.

Core MATLAB Functions Supporting simscape.Value Arrays

You can use core MATLAB array functions when working with simscape.Value arrays. The tables list additional restrictions that pertain to using simscape.Value arguments.

simscape.Value Math Functions

NameDescription
absAbsolute value
acosInverse cosine
asinInverse sine
atanInverse tangent
atan2Four quadrant inverse tangent
cosCosine
coshHyperbolic cosine
crossCross product
diffDifference
dotDot product
expExponential
logNatural logarithm
log10Common (base 10) logarithm
maxMaximum elements of an array
minMinimum elements of an array
modModulus after division
prodProduct of elements
signSignum function
sinSine
sinhHyperbolic sine
sqrtSquare root
sumSum of elements
tanTangent
tanhHyperbolic tangent

simscape.Value Operations

NameDescription
+ (plus), - (minus)Unary and binary plus and minus
* (mtimes), .* (times)Multiplication
/ (mrdivide), \ (mldivide), ./ (rdivide), .\ (ldivide)Division
== (eq), ~= (ne), < (lt), <= (le), > (gt), >= (ge)Relational
^ (mpower), .^ (power)Power

simscape.Value Inspection

NameDescription
isequalCompares two simscape.Value objects. Returns 1 if both arrays are the same size, contain the same values, and have the same unit, and 0 otherwise.
isequalnCompares two simscape.Value objects, treating NaN elements as equal to each other. Returns true if both arrays are the same size, contain the same values, and have the same unit, and 0 otherwise.
isfiniteReturns 1 for finite array elements, and 0 otherwise.
isinfReturns 1 for infinite array elements, and 0 otherwise.
isnanReturns 1 for NaN array elements, and 0 otherwise.

simscape.Value Type Conversions

NameDescription
double

For a dimensionless argument only, converts array elements to double precision. Dimensionless quantities are implicitly converted to unitless before conversion to double. For example:

double(simscape.Value(1,'m')/simscape.Value(2,'cm'))
ans =

    50
logical

Converts numeric values to logicals. Supported for simscape.Value objects with nonaffine units. Zero values, regardless of linear unit, are treated as false and nonzero values are treated as true.

Core MATLAB Functions Supporting simscape.Unit Arrays

The basic multiplication, division, power, and relational operations are defined on simscape.Unit. The table lists additional restrictions that pertain to using simscape.Unit arguments.

simscape.Unit Arithmetic and Relational Operations

NameDescription
timesElementwise unit products
mtimesMatrix unit products
rdivide, ldivideElementwise unit quotients
mrdivide, mldivideMatrix unit quotients. Supported, but denominator must be a scalar simscape.Unit object.
powerElementwise power. Base must be a simscape.Unit object. Exponent must be a compatibly sized numeric array. See also Fractional and Rational Exponents.
mpowerMatrix power. Supported, but requires base and exponent to be scalar.
eq, neDetermine equality or inequality. Compares units in canonical form.
isequalDetermine array equality. True if the unit arrays are the same size and all units are equivalent.

simscape.Unit Type Conversions

NameDescription
string

Converts each element of a unit array into a string. Returns a string array.

cellstr

Converts a unit array into a cell array of character vectors.

charConverts a unit array into a character array.

For example, create a 2x3 unit array:

u1 = simscape.Unit(["kg", "g", "lb"; "km", "m", "mm"])
u1 = 

    2×3 unit array

    kg    g    lb
    km    m    mm

Convert unit array into a string array:

string(u1)
ans = 

  2×3 string array

    "kg"    "g"    "lb"
    "km"    "m"    "mm"

Convert the same unit array into a cell array of character vectors:

cellstr(u1)
ans =

  2×3 cell array

    {'kg'}    {'g'}    {'lb'}
    {'km'}    {'m'}    {'mm'}

Convert the same unit array into a character array:

char(u1)
ans =

  6×2 char array

    'kg'
    'km'
    'g '
    'm '
    'lb'
    'mm'

Computational Units

When a math operation, such as addition, requires a computational unit, the return unit is the operand unit whose conversion factor to the fundamental unit is the largest. For example:

simscape.Value(2.2,'cm') + simscape.Value(2,'mm')
ans =

    2.4000 : cm

The fundamental unit for length is m. The conversion factor of cm into m is larger than that of mm into m, therefore, the return unit when adding cm and mm is cm.

Multiplication and division operations do not require a computational unit. These operations are performed by multiplying (dividing) the values and multiplying (dividing) the units. For example:

simscape.Value(2.2,'N') * simscape.Value(2,'m')
ans =

    4.4000 : N*m

Fractional and Rational Exponents

Fractional exponents are supported for simscape.Value objects. The numeric value is raised to the double power specified by the function and a rational approximation of the fractional exponent is applied to the units.

For simscape.Unit objects, exponents must be rational numbers. When computing unit powers, simscape.Unit uses the same rational fraction approximation as the MATLAB rat function.

Operations with Affine Units

simscape.Value objects can have affine units. For more information, see About Affine Units.

The following operations are prohibited on values with affine unit:

  • Forming compound units that include affine units.

  • Basic array operations that require unit conversion.

  • Implicit or explicit comparison to 0.

Limitations

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

    For example, to programmatically set a block parameter based on a simscape.Value object:

    x = simscape.Value(V, U);
    set_param(block, 'x', mat2str(value(x)));
    set_param(block, 'x_unit', char(unit(x)));
    
  • You cannot use simscape.Value or simscape.Unit objects to specify values with units or perform unit computations in Symbolic Math Toolbox™.

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