Working with simscape.Value and simscape.Unit Objects

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

Name	Description
`abs`	Absolute value
`acos`	Inverse cosine
`acosh`	Inverse hyperbolic cosine
`asin`	Inverse sine
`asinh`	Inverse hyperbolic sine
`atan`	Inverse tangent
`atan2`	Four quadrant inverse tangent
`atanh`	Inverse hyperbolic tangent
`cos`	Cosine
`cosh`	Hyperbolic cosine
`cross`	Cross product
`diff`	Difference
`dot`	Dot product
`exp`	Exponential
`log`	Natural logarithm
`log10`	Common (base 10) logarithm
`max`	Maximum elements of an array
`min`	Minimum elements of an array
`mod`	Modulus after division
`prod`	Product of elements
`sign`	Signum function
`sin`	Sine
`sinh`	Hyperbolic sine
`sqrt`	Square root
`sum`	Sum of elements
`tan`	Tangent
`tanh`	Hyperbolic tangent
`erf`	Error function
`erfc`	Complementary error function

simscape.Value Operations

Name	Description
`+` (`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

Name	Description
`isequal`	Compares 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.
`isequaln`	Compares 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.
`isfinite`	Returns `1` for finite array elements, and `0` otherwise.
`isinf`	Returns `1` for infinite array elements, and `0` otherwise.
`isnan`	Returns `1` for NaN array elements, and `0` otherwise.

simscape.Value Type Conversions

Name	Description
`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

Name	Description
`times`	Elementwise unit products
`mtimes`	Matrix unit products
`rdivide`, `ldivide`	Elementwise unit quotients
`mrdivide`, `mldivide`	Matrix unit quotients. Supported, but denominator must be a scalar `simscape.Unit` object.
`power`	Elementwise power. Base must be a `simscape.Unit` object. Exponent must be a compatibly sized numeric array. See also Fractional and Rational Exponents.
`mpower`	Matrix power. Supported, but requires base and exponent to be scalar.
`eq`, `ne`	Determine equality or inequality. Compares units in canonical form.
`isequal`	Determine array equality. True if the unit arrays are the same size and all units are equivalent.

simscape.Unit Type Conversions

Name	Description
`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.
`char`	Converts 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.