Working with Custom Unit Databases

In Simulink^® models, you specify units from a unit database. The unit database comprises units from the following unit systems:

SI — International System of Units
SI (extended) — International System of Units (extended)
English — English System of Units
CGS — Centimetre-gram-second System of Units

By default, Simulink supports only the units and unit systems listed in Allowed Units. To introduce additional units from other unit systems at a system-wide level and use those new units as you would those listed in Allowed Units, create and load a new unit database with these functions:

createCustomDBFromExcel — Creates a custom unit database file from an Excel^® spreadsheet that contains definitions for the custom unit database. On all supported platforms, the createCustomDBFromExcel function supports: .xls and .xlsx files.
rehashUnitDBs — Loads custom unit databases by rehashing unit database files on the MATLAB^® path.

Custom Units Spreadsheet Format

Spreadsheets must have these columns in any order:

name — Unit name, using any graphical Unicode characters except @, *, /, ^, (,), +, \, ", ', {, }, [, ], <, >, &, -, ::, and white space.
symbol — Symbol of unit, using any graphical Unicode characters except @, *, /, ^, (,), +, \, ", ', {, }, [, ], <, >, &, -, ::, and white space.
asciiSymbol — Symbol of unit, in ASCII.
displayName — Name of unit displayed in model in LaTeX format.
definitionExpression — Definition of the unit in terms of predefined units, such as seven base SI units.
conversionFactor — Conversion factor between the unit and its definition.
conversionOffset — Conversion offset between the unit and its definition.
physicalQuantity — Valid physical quantities. See table 'Physical Quantities' in showunitslist.
provenance — Optional column. List of unit provenances, separated by commas.

Follow these guidelines when developing spreadsheets:

If the input spreadsheet contains more then one worksheet, you must name the worksheets with the prefixes unit, physicalQuantity, or provenance.
If there are multiple instances of a prefix in a worksheet, the function uses all of the worksheets to create the database:
- unit — Creates units
- physicalQuantity — Creates physical quantities
- provenance — Creates provenances

Optionally, you can define physical quantities in another worksheet of the input spreadsheet. A worksheet defining physical quantities contains these columns in any order:

name — Physical quantity name, using any graphical Unicode characters except @, *, /, ^, (,), +, \, ", ', {, }, [, ], <, >, &, -, ::, and white space.
definitionExpression — Definition of physical quantity in terms of predefined physical quantities.
provenance — Optional. List of physical quantity provenances, separated by commas.

Optionally, you can also define provenances in another worksheet of the input spreadsheet. A worksheet defining provenances contains these columns in any order:

identifier — Identifier of provenance
title — Title of provenance
subTitle — Subtitle of provenance
organization — Organization of provenance
fullName — Full name of provenance
urlList — List of URL links of provenance
edition — Provenance edition
year — Provenance year

Define Custom Units in Excel Spreadsheet

First, create an Excel spreadsheet following the guidelines in Custom Units Spreadsheet Format. Use unit definitions, one per row, such as:

Save this spreadsheet in a file such as unitsDB.xlsx. You can then create the database and load it.

Create and Load Custom Unit Database

Open Live Script

This example shows how to create a custom units database and then load it.

Create the database using the spreadsheet included in this example.

createCustomDBFromExcel('unitsDB.xlsx')

The function creates unitsDB.slunitdb.mldatx in the current folder.

Load the new units database into memory.

rehashUnitDBs

To verify that the new database has been loaded, open the slex_customunits model and apply custom units on any of the output ports:

slex_customunits

Documentation