sbiounit

Create user-defined unit

You can no longer specify an offset as an input when you call sbiounit. Use an absolute unit that does not require an offset. For details, see Version History.

Syntax

unitObject = sbiounit('NameValue') unitObject = sbiounit('NameValue', 'CompositionValue') unitObject = sbiounit('NameValue','CompositionValue',MultiplierValue) unitObject = sbiounit('NameValue','CompositionValue',...'PropertyName', PropertyValue...)

Arguments

`NameValue`	Name of the user-defined unit. `NameValue` must begin with characters and can contain characters, underscores, or numbers. `NameValue` can be any valid MATLAB^® variable name.
`CompositionValue`	Shows the combination of base and derived units that defines the unit `NameValue`. For example `molarity` is `mole/liter`. Base units are the set of units used to define all unit quantity equations. Derived units are defined using base units or mixtures of base and derived units.
`MultiplierValue`	Numerical value that defines the relationship between the user-defined unit `NameValue` and the base unit as a product of the `MultiplierValue` and the base unit. For example, `1 mole` is `6.0221e23*molecule`. The `MultiplierValue` is `6.0221e23`.
`PropertyName`	Name of the unit object property, for example,`'Notes'`.
`PropertyValue`	Value of the unit object property, for example, `'New unit for GPCR model'`.

Description

unitObject = sbiounit('NameValue') constructs a SimBiology^® unit object named NameValue. Valid names must begin with a letter, and be followed by letters, underscores, or numbers.

unitObject = sbiounit('NameValue', 'CompositionValue') allows you to specify the name and the composition of the unit.

unitObject = sbiounit('NameValue','CompositionValue',MultiplierValue) creates a unit with the name NameValue where the unit is defined as MultiplierValue*CompositionValue.

unitObject = sbiounit('NameValue','CompositionValue',...'PropertyName', PropertyValue...) defines optional properties. The name-value pairs can be in any format supported by the function set.

In order to use unitObject, you must add it to the user-defined library with the sbioaddtolibrary function. To get the unit object into the user-defined library, use the following command:

sbioaddtolibrary(unitObject);

You can view additional unitObject properties with the get command. You can modify additional properties with the set command. For more information about unit object properties and methods, see Unit object.

Use the sbiowhos function to list the units available in the user-defined library.

Examples

This example shows you how to create a user-defined unit, add it to the user-defined library, and query the library.

Create units for the rate constants of a first-order and a second-order reaction.

unitObj1 = sbiounit('firstconstant', '1/second', 1);
unitObj2 = sbiounit('secondconstant', '1/molarity*second', 1);

Add the unit to the user-defined library.
```
sbioaddtolibrary(unitObj1);
sbioaddtolibrary(unitObj2);
```

Query the user-defined library in the root object.

rootObj = sbioroot;
rootObj.UserDefinedLibrary.Units

ans = 

   SimBiology Unit Array

   Index:    Library:       Name:             Composition:         Multiplier:
   1         UserDefined    firstconstant     1/second             1          
   2         UserDefined    secondconstant    1/molarity*second    1

Alternatively, use the sbiowhos command.

sbiowhos -userdefined -unit

   SimBiology UserDefined Units
                                   
   Index:  Name:           Composition:             Multiplier:     
   1       firstconstant   1/second                 1.000000        
   2       secondconstant  1/molarity*second        1.000000

Version History

Introduced in R2008a

expand all

R2022b: `week` has been added as a built-in unit

You can now use week as a built-in unit and no longer have to create your own custom week unit. However, suppose that you have added a custom week unit to the user-defined (custom) library in a previous release (R2022a or earlier), installed the new version of MATLAB (R2022b or later), and your preferences from the previous release was imported (automatically by MATLAB or manually by you). When you interact with SimBiology for the first time in your latest MATLAB, SimBiology:

Switches to use the built-in week unit.
Renames the custom unit to week_N, where N is a positive integer.
Shows a one-time warning message indicating that your custom week unit has been renamed.

Use sbioremovefromlibrary at the command line or go to Home > Libraries from the SimBiology Model Builder app to remove the custom unit if it is no longer needed.

Tip

Check the model component properties, namely, Notes, Tag, and UserData, to see if the custom unit is being referenced by these properties before removing the unit.
Update references to use the new name (week_N) if the built-in week unit is not sufficient for your use case.

R2021a: `sbiounits` no longer accepts offset as an input

You can no longer specify an offset information as an input when you call sbiounits. The Offset property of a unit object has been removed. Use an absolute unit that does not require an offset, such as kelvin instead of Celsius.

R2021a: Celsius and Fahrenheit units have been removed

Celsius, celsius, and fahrenheit units have been removed from the built-in units library. Use kelvin units instead.

If you have a model containing Celsius, celsius, or fahrenheit units, change the units to kelvin.

If you have a script that sets the Units property of a SimBiology.Parameter object to 'Celsius', 'celsius', or 'fahrenheit', set this property to 'kelvin' and adjust the Value property accordingly. Similarly, if you have compound units, make appropriate changes. For example, change joule/Celsius to joule/kevin.