SimBiology.UnitPrefix

R2026b

Hold information about user-defined unit prefix

Description

The SimBiology.UnitPrefix object contains information about user-defined unit prefixes. Use the object property Exponent to specify the exponent of your unit prefix.

Use dot notation to query the object properties or change properties that are not read-only. You can also use the get and set commands. findUsages lets you find out how a unit prefix is used in the built-in and custom libraries.

The SimBiology Model Builder app also enables you to change unit prefixes present in the libraries. For more information, see SimBiology Model Component Libraries.

Creation

Create a UnitPrefix object using sbiounitprefix and add the object to the library using sbioaddtolibrary.

Properties

Exponent — Exponent value of unit prefix

0 (default) | nonnegative integer

Exponent value of a unit prefix, specified as a nonnegative integer.

The property defines the numerical (exponent) value of the unit prefix. You can use the unit prefix in conjunction with any built-in or user-defined units. For example, you can define a unit prefix object petaPrefix with the Exponent property value set to 15.

Data Types: double

Name — SimBiology.UnitPrefix object name

character vector | string scalar

SimBiology.UnitPrefix object name, specified as a character vector or string scalar.

For details on requirements and recommendations for naming SimBiology^® components, see Guidelines for Naming Model Components.

Data Types: char | string

Notes — Additional information

empty character array (default) | character vector | string scalar

Additional information that you can add for the SimBiology object, specified as a character vector or string scalar.

Data Types: char | string

Parent — Parent object

Read-only: [] | root object

This property is read-only.

Parent object, specified as [] or root object. The default property value is [] until you add the UnitPrefix object to the library. Then the value becomes a root object upon addition to the library.

Tag — Object label

empty character array (default) | character vector | string scalar

Object label, specified as a character vector or string scalar.

This property will be removed in a future release. Use Tags instead.

Data Types: char | string

Tags — Object labels

empty string array (default) | character vector | string scalar | string vector | cell array of character vectors

Since R2026b

Object labels, specified as a character vector, string scalar, string vector, or cell array of character vectors. The property value is stored and returned as a string vector.

Use the property to assign multiple tags to the object, for example, to classify and group model components for selection and organization and then use sbioselect to retrieve the components.

When you load a model having components that have a nonempty Tag property value, and the Tags property is empty, the software copies the Tag value into Tags as a scalar string.

Type — Object type

Read-only: 'unitprefix' (default)

This property is read-only.

Object type, specified as 'unitprefix'. When you create a SimBiology object, the value of Type is automatically defined.

Data Types: char

UserData — Data to associate with object

[] (default) | array

Data to associate with the object, specified as any MATLAB array. For example, you can specify a scalar, vector, character vector, table, or structure. Use this property to store arbitrary data on an object.

The object does not use this data directly, but you can access it using dot notation or get.

Object Functions

delete	Delete SimBiology object
findUsages	Find out how a unit or unit prefix is used
get	Get SimBiology object properties
rename	Rename SimBiology model component and update expressions
set	Set SimBiology object properties

Examples

Create a Custom Unit Prefix and Add to Library

Create a unit prefix peta with the exponent value of 15.

petaPrefix = sbiounitprefix("peta",15);

Add the unit prefix to the library.

sbioaddtolibrary(petaPrefix);

Check that peta has been added as a user-defined unit prefix.

sbiowhos -userdefined -unitprefix

   SimBiology UserDefined Unit Prefixes
           
   Index:  Name:           Multiplier:              
   1       peta            1000000000000000         

You can also use sbioshowunitprefixes or the root object.

sbioshowunitprefixes

ans = 
   SimBiology Unit Prefix Array

   Index:    Library:       Name:    Exponent:
   1         BuiltIn        centi    -2       
   2         BuiltIn        deci     -1       
   3         BuiltIn        deka     1        
   4         BuiltIn        femto    -15      
   5         BuiltIn        giga     9        
   6         BuiltIn        hecto    2        
   7         BuiltIn        kilo     3        
   8         BuiltIn        mega     6        
   9         BuiltIn        micro    -6       
   10        BuiltIn        milli    -3       
   11        BuiltIn        nano     -9       
   12        UserDefined    peta     15       
   13        BuiltIn        pico     -12      
   14        BuiltIn        tera     12       

rootObj = sbioroot;
rootObj.UserDefinedLibrary.UnitPrefixes

ans = 
   SimBiology Unit Prefix Array

   Index:    Library:       Name:    Exponent:
   1         UserDefined    peta     15       

Define a Custom Unit in SimBiology

Create a user-defined unit called usermole, whose Composition property is molecule and Multiplier property is 6.0221e23.

unitObj = sbiounit('usermole','molecule',6.0221e23); 

Add the unit to the user-defined library.

sbioaddtolibrary(unitObj);

Query the Multiplier property.

unitObj.Multiplier

ans = 
6.0221e+23

Version History

Introduced in R2008a

R2026b: Tags property added

Use the Tags property to assign multiple tags to the object. When you load a model having components that have a nonempty Tag property value, and the Tags property is empty, the software copies the Tag value into Tags as a scalar string.

R2026b: Tag property will be removed

The Tag property will be removed in a future release. Use the Tags property instead.

R2024a: Having duplicate model component names is no longer allowed

• When you load a model that contains duplicate names, SimBiology automatically updates those names. SimBiology disambiguates the duplicate names by adding a suffix "_N", where N is the first positive integer that results in a unique name. If there is an existing suffix, N will be incremented from that suffix. For example, if there are two model components named x_3, the function updates one of the names to x_4. If the existing suffix has leading zeros, the function omits the zeros in the new name. For instance, if x_003 is a duplicate name, it gets renamed to x_4. However, the function assumes that names with leading zeros and without leading zeros are different. For instance, x_005 and x_5 are considered to be different names.

• SimBiology issues an error if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. Within a single model, these components are required to have unique names even when they are of different types with the following two exceptions:

  • Species in different compartments can have the same name.

  • Parameters can have the same name if they are scoped to different parents. Specifically, you can use the same name for a model-scoped parameter and reaction-scoped parameters, where each reaction-scoped parameter belongs to a different reaction.

  For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.

R2022b: Having duplicate model component names issues a warning

SimBiology issues a warning if multiple model components have the same name.

R2022a: Having duplicate model component names will not be allowed in a future release

SimBiology will not allow you to have duplicate names for model components within a model.