Manage Design Data for Simulink Models Programmatically

A Simulink^® model can use many different data sources to contain the variables and data objects that you use to specify block parameters and signal characteristics in the model and its generated code. To manage these data sources programmatically:

Create a connection to the data source.
Use a common set of functions to manage the data.

Connect to a Data Source

To manage a data source programmatically, first use the Simulink.data.connect function to create a Simulink.data.DataConnection object for the data source. You can create a data connection object for the base workspace, model workspace, or the Design Data section of a data dictionary.

bw = Simulink.data.connect('base workspace');
mw = Simulink.data.connect("model.slx");
dd = Simulink.data.connect('model_dd.sldd');

To get a list of functions you can use on the object, on the command line, press the Tab button after typing the connection object name and . operator.

The Simulink.data.connect function provides the option to configure tab completion to include only object functions (the default behavior), only variables contained in the data source, or both functions and variables. After you create the data connection object, you cannot change the tab completion configuration.

% default behavior
bw = Simulink.data.connect('base workspace', 'Methods');
% Only variables contained in the data source
mw = Simulink.data.connect("model.slx", 'Vars');
% Both object functions and variables 
dd = Simulink.data.connect('model_dd.sldd', 'All');

If you change the contents of the data source outside of the data connection object (through a user interface, data source-specific functions, or other data connection), variables listed by tab completion might be out of sync with the list of variables in the data source. To update the variables in the tab completion list, use the object function syncTabComplete.

Manage Variables in a Data Source

After you create a data connection object for your data source, you can use the object functions to manage the data.

Read and Assign Variables

To read or assign variables in the data source, use the '.' operator or the object functions get and set.

dd.x = 10;
set(mw, 'y', 20);
dd.x = dd.x + mw.y;
get(dd, 'x')

ans = 

    30

You can also use the object functions get and set to read and assign multiple variables.

set(dd, ["c" "d"], {3,4});
get(dd, ["c" "d"}

ans = 

1x2 cell array

    {[3]}    {[4]}

If you assign a value to a variable that does not exist in the data source, the function creates a new variable. If the data source is a data dictionary with referenced dictionaries, the function creates the new variable in the top level dictionary.

If you read a variable that does not exist in the data source, the get function returns the value missing.

set(mw, {'e','f'}, {5,6});
get(mw, {'e', 'x', 'f'})

ans = 

1x3 cell array

    {[5]}    {[missing]}    {[6]}

Create Objects

To create new objects in a connected data source, use the create function. You can create:

Variables
Enumerations of type Simulink.data.dictionary.EnumTypeDefinition

Note
You cannot create new enumeration types by using the . operator or the set function.
Objects from the Simulink package (for supported package members, see create)
String expressions that are valid data object constructors (for example, 'fixdt(1,16,12)' or 'single(10)')

For some types, you can call the create function with additional named arguments to further configure the created object:

'Enum'
- Enumerals
- EnumValue
'Bus'
- BusElementNames

List Variables

To know the contents of a connected data source, you have these options:

who — Lists variables in the data source.
exist — Checks if a specified variable exists in the data source.
show — Opens the data source and displays the contents in Model Explorer.

Rename Variables

To rename a specific variable or multiple variables in a connected data source, call the rename function. To successfully rename a variable in the data source, the variable name must exist, and the new variable name must not exist.

dd = Simulink.data.connect('model_dd.sldd', TabComplete = 'Vars')
dd.ax = 3;
dd.ay = 4;
success = rename(dd, {'ax', 'ay'}, {'bx', 'by'})

1x2 logical array
    1    1

Remove Variables

Remove specific variables from a connected data source or remove all variables in the data source by calling the clear and clearAll functions.

mw = Simulink.data.connect("vdp.slx");
clear(mw, 'x');
clear(mw, ["y" "z"]);
clearAll(mw);

Manage Changes to a Data Source

When you have completed your changes to the connected data source, you can choose to save or discard those changes by calling the saveChanges or the discardChanges function. To determine if there are changes in memory that have not yet been saved to disk, call the hasUnsavedChanges.

Manage Data Consistency in a Data Source

A data connection might see multiple definitions of the same variable (for example, in a data dictionary and in a referenced dictionary). Multiple definitions of the same variable are considered consistent if the properties of the objects are identical. The object functions that manage variables in a connected data source can operate with multiple definitions as long as the definitions are consistent.

Object Function	Behavior for Multiple Definitions
`get` and dot reference	Returns one of the definitions or reports an error if the definitions are inconsistent
`set` and dot assign	If definitions exist, updates each definition
`who`	Lists variable name once for each definition
`clear(var)`	Removes each definition matching `var`
`exist(var)`	Returns `true` if a variable with the name `var` exists
`rename(var)`	Renames each definition
`getMetadata(varName)`	Returns an array that contains a metadata structure for each definition

Handling Inconsistent Definitions

You can determine if a variable has inconsistent definitions by calling the isConsistent function. You can identify the inconsistencies for the variable, or all variables visible to the data connection, by calling the reportInconsistency function. This function returns a dictionary object that contains a list of variables that have multiple inconsistent definitions. Each entry in the dictionary maps one of these variables to an array of structures. The structures provide the value and metadata for each definition so that you can identify the inconsistencies. For more information on the metadata available for each type of data source, see getMetadata.

For example, to determine if there are inconsistencies in your data dictionary, first get an inconsistency report for the dictionary.

dd = Simulink.data.connect('a.sldd');
rpt = reportInconsistency(dd)

r = 

dictionary (string --> cell) with 2 entries

   "kp"         --> {1x3 struct array}
   "kb"         --> {1x2 struct array}

In this case, the report identifies two variables, kp and kb that have multiple inconsistent definitions visible to the data connection. Examine the inconsistencies for one of these variables, kb, by looking at the each of its definitions.

Get the dictionary item that maps kb to an array of structures that provide the value and metadata for each definition.
```
rpt_kb = rpt("kb")
```
```
rpt_kb = 

 1x2 struct array with fields:

    value
    metadata
```

Look at the value and metadata for each kb definition.

rpt_kb(1).value

ans = 

1.5

rpt_kb(2).metadata

dictionary (string --> cell) with 5 entries

    "DataSource"       --> {'a.sldd'}
    "Section"          --> {'Design Data'}
    "LastModified"     --> {'2023-Jun-04 02:34:37.530062'}
    "LastModifiedBy"   --> {'user'}
    "Status"           --> {'Unchanged'}

rpt_kb(2).value

ans = 

1.6

rpt_kb(2).metadata

dictionary (string --> cell) with 5 entries

    "DataSource"       --> {'ra.sldd'}
    "Section"          --> {'Design Data'}
    "LastModified"     --> {'2023-Jun-05 01:30:18.130062'}
    "LastModifiedBy"   --> {'user2'}
    "Status"           --> {'Unchanged'}

Note that the two definitions for kb have different values.

Fix each inconsistency by using one of these approaches:
- Make the value for each definition consistent.
- Delete all but one of the variable definitions.
- Rename all but one of the variable definitions.

Manage Source-Specific Data Tasks

For most common data management tasks you can use the Simulink.data.connect function to create a connection to your data source, then use the common set of functions provided by the Simulink.data.DataConnection object. For data source-specific tasks, create a data source-specific object, then use the functions provided by that object to manage your data.

Model workspace — Simulink.ModelWorkspace
Data dictionary — Simulink.data.Dictionary
Custom file formats — Simulink.data.adapters.BaseMatlabFileAdapter