## 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
`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

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

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

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.

`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.