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 pagewise 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
andb
, as arguments.Extracts values from
a
andb
.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 
asin  Inverse sine 
atan  Inverse tangent 
atan2  Four quadrant inverse 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
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

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
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
orsimscape.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
orsimscape.Unit
objects to specify values with units or perform unit computations in Symbolic Math Toolbox™.MATLAB Coder™ does not support
simscape.Value
andsimscape.Unit
objects.