Data Objects

You can create data objects to specify values, value ranges, data types, tunability, and other characteristics of signals, states, and block parameters. You use the object names in Simulink^® dialog boxes to specify signal, state, and parameter characteristics. The objects exist in a workspace such as the base workspace, a model workspace, or a Simulink data dictionary. Data objects allow you to make model-wide changes to signal, state, and parameter characteristics by changing only the values of workspace objects.

You create data objects as instances of data classes. Memory structures called data class packages contain the data class definitions. The built-in package Simulink defines two data classes, Simulink.Signal and Simulink.Parameter, that you can use to create data objects. To store lookup table data for sharing between lookup table blocks (such as n-D Lookup Table), you can use the Simulink.LookupTable and Simulink.Breakpoint classes.

To decide whether to use data objects to configure signals, including Inport and Outport blocks, see Store Design Attributes of Signals and States.

You can customize data object properties and methods by defining subclasses of the built-in data classes. For more information about creating a data class package, see Define Data Classes.

Data Class Naming Conventions

Simulink uses dot notation to name data classes:

package.class

• package is the name of the package that contains the class definition.

• class is the name of the class.

This notation allows you to create and reference identically named classes that belong to different packages. In this notation, the name of the package qualifies the name of the class.

Class and package names are case sensitive. For example, you cannot use MYPACKAGE.MYCLASS and mypackage.myclass interchangeably to refer to the same class.

Use Data Objects in Simulink Models

To specify simulation and code generation options for signals, block parameters, and states by modifying variables in a workspace or data dictionary, use data objects. Associate the objects with signals, parameters, and states in a model diagram.

Use Parameter Objects

You can use parameter objects, instead of numeric MATLAB^® variables, to specify values for block parameters. For example, to create and use a Simulink.Parameter object named myParam to specify the Gain parameter of a Gain block:

1. In the model, on the Modeling tab, under Design, click Property Inspector.

2. In the model, click the target Gain block. The Property Inspector shows the properties and parameters of the block.

3. Set the value of the Gain parameter to myParam.

4. Next to the parameter value, click the action button and select Create.

5. In the Create New Data dialog box, set Value to Simulink.Parameter(15.23) and click Create.

   The Simulink.Parameter object, myParam, appears in the base workspace. The property dialog box shows that the object stores the parameter value 15.23 in the Value property.

6. Use the property dialog box to specify other characteristics for the block parameter by adjusting the object properties. For example, to specify the minimum and maximum values the parameter can take, use the Minimum and Maximum properties.

During simulation, the Gain parameter now uses the value 15.23.

To share lookup table data by using Simulink.LookupTable and Simulink.Breakpoint objects, see Package Shared Breakpoint and Table Data for Lookup Tables.

Use Signal Objects

You can associate a signal line or block state, such as the state of a Unit Delay block, with a signal object.

For Signals.  To use a signal object to control the characteristics of a signal in a model, create the object in a workspace by using the same name as the signal.

1. In the model, on the Modeling tab, click Model Data Editor.

2. In the Model Data Editor, select the Signals tab.

3. In the model, select the target signal. The Model Data Editor highlights the row that corresponds to the signal.

4. In the Model Data Editor, in the Name column, give the signal a name such as mySig.

5. Click the button next to the signal name. Select Create and Resolve.

6. In the Create New Data dialog box, set Value to Simulink.Signal. Use the Location drop-down list to select a workspace to store the object (the default value is Base Workspace). Click Create.

   The Simulink.Signal object mySig appears in the target workspace. Simulink selects the signal property Signal name must resolve to Simulink signal object, which forces the signal in the model to use the properties that the signal object stores. To learn how to control the way that signal names resolve to signal objects, see Symbol Resolution.

   The property dialog box of the new object opens.

7. Use the property dialog box to specify the signal characteristics. Click OK.

To configure the signal programmatically:

% Create the signal object.
mySig = Simulink.Signal;
mySig.DataType = 'boolean';

% Get a handle to the block port that creates the
% target signal.
portHandles = get_param('myModel/myBlock','portHandles');
outportHandle = portHandles.Outport;

% Specify the programmatic port parameter 'Name'.
set_param(outportHandle,'Name','mySig')

% Set the port parameter 'MustResolveToSignalObject'.
set_param(outportHandle,'MustResolveToSignalObject','on')

To configure a root-level Outport block programmatically, you must use a slightly different technique:

% Create the signal object.
mySig = Simulink.Signal;
mySig.DataType = 'boolean';

% Specify the programmatic block parameter 'SignalName'.
set_param('myModel/myOutport','SignalName','mySig')

% Set the block parameter 'MustResolveToSignalObject'.
set_param('myModel/myOutport','MustResolveToSignalObject','on')

For States.  You can use a signal object to control the characteristics of a block state, such as that of the Discrete-Time Integrator block.

1. In the model, on the Modeling tab, click Model Data Editor.

2. In the Model Data Editor, select the States tab.

3. In the model, select the block that harbors the target state. The Model Data Editor highlights the row that corresponds to the state.

4. In the Model Data Editor, in the Name column, give the state a name such as myState.

5. Click the button next to the state name. Select Create and Resolve.

6. In the Create New Data dialog box, set Value to Simulink.Signal. Use the Location drop-down list to select a workspace to store the object (the default value is Base Workspace). Click Create.

   The Simulink.Signal object myState appears in the target workspace. Simulink selects the block parameter State name must resolve to Simulink signal object, which forces the state in the model to use the properties that the signal object stores. To learn how to control the way that state names resolve to signal objects, see Symbol Resolution.

   The property dialog box of the new object opens.

7. Use the property dialog box to specify the state characteristics. Click OK.

To configure the state programmatically:

% Create the signal object.
myState = Simulink.Signal;
myState.DataType = 'int16';

% Set the state name in the block.
set_param('myModel/myBlock','StateName','myState')

% Set the port parameter 'StateMustResolveToSignalObject'.
set_param('myModel/myBlock','StateMustResolveToSignalObject','on')

Data Object Properties

To control parameter and signal characteristics using data objects, you specify values for the data object properties. For example, parameter and signal data objects have a DataType property that determines the data type of the target block parameter or signal. Data class definitions determine the names, value types, default values, and valid value ranges of data object properties.

You can use either the Model Explorer or MATLAB commands to change a data object's properties.

For a list of signal object properties, see Simulink.Signal. For a list of parameter object properties, see Simulink.Parameter.

Use the Model Explorer to Change an Object's Properties

To use the Model Explorer to change an object's properties, select the workspace that contains the object in the Model Explorer's Model Hierarchy pane. Then select the object in the Model Explorer's Contents pane.

The Model Explorer displays the object's property dialog box in its Dialog pane (if the pane is visible).

You can configure the Model Explorer to display some or all of the properties of an object in the Contents pane (see Model Explorer). To edit a property, click its value in the Contents or Dialog pane. The value is replaced by a control that allows you to change the value.

Use MATLAB Commands to Change an Object's Properties

You can also use MATLAB commands to get and set data object properties. Use the following dot notation in MATLAB commands and programs to get and set a data object's properties:

value = obj.property;
obj.property = value;

where obj is a variable that references either the object if it is an instance of a value class or a handle to the object if the object is an instance of a handle class (see Handle Versus Value Classes), PROPERTY is the property's name, and VALUE is the property's value. For example, the following MATLAB code creates a data type alias object (i.e., an instance of Simulink.AliasType) and sets its base type to uint8:

gain = Simulink.AliasType;
gain.BaseType = 'uint8';

You can use dot notation recursively to get and set the properties of objects that are values of other object's properties, e.g.,

gain.CoderInfo.StorageClass = 'ExportedGlobal';

Create Data Objects from Built-In Data Class Package Simulink

The built-in package Simulink defines two data object classes Simulink.Parameter and Simulink.Signal. You can create these data objects using the user interface or programmatically.

Create Data Objects

1. In the Model Explorer Model Hierarchy pane, select a workspace to contain the data objects. For example, click Base Workspace.

2. On the toolbar, click the arrow next to Add Parameter or Add Signal . From the drop-down list, select Simulink Parameter or Simulink Signal.

   A parameter or signal object appears in the base workspace. The default name for new parameter objects is Param. The default name for new signal objects is Sig.

3. To create more objects, click Add Parameter or Add Signal.

To create Simulink.LookupTable and Simulink.Breakpoint objects, on the Model Explorer toolbar, use the button.

Programmatically Create Data Objects

% Create a Simulink.Parameter object named myParam whose value is 15.23.
myParam = Simulink.Parameter(15.23);

% Create a Simulink.Signal object named mySig.
mySig = Simulink.Signal;

Convert Numeric Variable into Parameter Object

You can convert a numeric variable into a Simulink.Parameter object as follows.

/* Define numeric variable in base workspace
myVar = 5; 
/* Create data object and assign variable value
myObject = Simulink.Parameter(myVar); 

Create Data Objects from Another Data Class Package

You can create your own package to define custom data object classes that subclass Simulink.Parameter and Simulink.Signal. You can use this technique to add your own properties and methods to data objects. If you have an Embedded Coder^® license, you can define storage classes and memory sections in the package. For more information about creating a data class package, see Define Data Classes.

Create Data Objects from Another Package

Suppose that you define a data class package called myPackage. Before you can create data objects from the package, you must include the folder containing the package folder on your MATLAB path.

1. In the Model Explorer Model Hierarchy pane, select a workspace to contain the data objects. For example, click Base Workspace.

2. Click the arrow next to Add Parameter or Add Signal and select Customize class lists.

3. In the dialog box, select the check box next to the class that you want. For example, select the check boxes next to myPackage.Parameter and myPackage.Signal. Click OK.

4. Click the arrow next to Add Parameter or Add Signal. Select the class for the data object that you want to create. For example, select myPackage Parameter or myPackage Signal.

   A parameter or signal object appears in the base workspace. The default name for new parameter objects is Param. The default name for new signal objects is Sig.

5. To create more data objects from the package myPackage, click Add Parameter or Add Signal again.

Programmatically Create Data Objects from Another Package

Suppose that you define a data class package called myPackage. Before you can create data objects from the package, you must include the folder containing the package folder on your MATLAB path.

% Create a myPackage.Parameter object named 
% myParam whose value is 15.23.
myParam = myPackage.Parameter(15.23);

% Create a myPackage.Signal object named mySig.
mySig = myPackage.Signal;

Create Data Objects Directly from Dialog Boxes

When you open a Signal Properties dialog box, a block dialog box, or the Property Inspector (on the Modeling tab, under Design, click Property Inspector), you can efficiently create a signal or parameter data object in a workspace or data dictionary.

Create Parameter Object from Block Dialog Box

1. In a numeric block parameter in the dialog box, specify the name that you want for the data object. For example, specify the name myParam.

2. Click the button next to the value of the block parameter. Select Create.

3. In the Create New Data dialog box, specify Value as Simulink.Parameter.

   Alternatively, you can specify the name of a data class that you created, such as myPackage.Parameter. You can also use the drop-down list to select from a list of available data object classes.

4. Specify Location as Base Workspace and click Create.

   You can use the Location option to select a workspace to contain the new data object. If a model is linked to a data dictionary, you can choose to create a data object in the dictionary.

5. In the dialog box that opens, configure the data object properties. Specify a numeric value for the parameter in the Value box. Click OK.

   The parameter object myParam appears in the base workspace.

6. In the block parameter dialog box, click OK.

Create Signal Object from Signal Properties Dialog Box

1. In the Signal name box, specify a signal name such as mySig. Click Apply.

2. Click the button next to the value of Signal name. Select Create and Resolve.

3. In the Create New Data dialog box, specify Value as Simulink.Signal.

   Alternatively, you can specify the name of a data class that you created, such as myPackage.Signal. Also, from the drop-down list, you can select a data object class that exists on the MATLAB path.

4. Specify Location as Base Workspace and click Create.

   You can use the Location option to select a workspace to contain the new data object. If a model is linked to a data dictionary, you can choose to create a data object in the dictionary.

5. In the dialog box that opens, configure the data object properties and click OK.

   The signal object mySig appears in the base workspace. In the Signal Properties dialog box, the Signal name must resolve to Simulink signal object property is selected.

Create Data Objects for a Model Using Data Object Wizard

To create data objects that represent signals, parameters, and states in a model, you can use the Data Object Wizard. The wizard finds data in the model that do not have corresponding data objects.

Based on specifications in the model, the wizard creates the objects and assigns these characteristics:

• Signal, parameter, or state name.

• Numeric value for parameter objects.

• Data type. For signal objects, includes alias types such as Sumlink.AliasType and Simulink.NumericType.

1. In the Simulink Editor, on the Modeling tab, under Design, click Data Object Wizard.

   

2. In the Model name box, enter the name of the model that you want to search.

   By default, the box contains the name of the model from which you opened the wizard.

3. Under Find options, select the check boxes next to the data object types that you want to create. The table describes the options.

   Option	Description
   Root inputs	Named signals from root-level Inport blocks.
   Root outputs	Named signals from root-level Outport blocks.
   States	States associated with these discrete blocks: Discrete Filter Discrete State-Space Discrete-Time Integrator Discrete Transfer Fcn Discrete Zero-Pole Memory Discrete PID Controller Discrete PID Controller (2DOF) Unit Delay
   Data stores	Data stores. For more information about data stores, see Local and Global Data Stores.
   Block outputs	Named signals whose sources are non-root-level blocks.
   Parameters	Numeric parameters, for example the parameters in these blocks: Constant Gain Relay Stateflow® data with Scope set to Parameter.
   Alias types	Data type replacement names that you specify in Configuration Parameters > Code Generation > Data Type Replacement. If you have an Embedded Coder license, the Data Object Wizard creates Simulink.AliasType objects for these data type replacement names. For more information about data type replacement, see Model Configuration Parameters: Code Generation Data Type Replacement (Embedded Coder)

4. Click Find.

   The data object table displays the proposed objects.

   

5. (Optional) To create objects from a data class other than the default classes, select the check box next to the objects whose class you want to change. To select all of the objects, click Select All. Click Change Class. In the dialog box that opens, select classes by using the drop-down lists next to Parameter and Signal.

   If the classes that you want do not appear in the drop-down list, select Customize class lists. In the dialog box that opens, select the check box next to the classes that you want, and click OK.

   To change the default parameter and signal classes that the wizard uses to propose objects:

   • On the Model Explorer Model Hierarchy pane, select a workspace. For example, select Base Workspace.

   • On the toolbar, click the arrow next to Add Parameter or Add Signal .

   • From the drop-down list, select the class that you want the wizard to use. For example, select myPackage Parameter or myPackage Signal.

     A parameter or signal object appears in the selected workspace. The default name for new parameter objects is Param. The default name for new signal objects is Sig.

     The next time that you use the Data Object Wizard, the wizard proposes objects using the parameter or signal class that you selected in Model Explorer.

6. Select the check box next to the proposed objects that you want to create. To select all of the proposed objects, click Select All.

7. Click Create.

   The data objects appear in the base workspace. If the target model is linked to a data dictionary, the objects appear in the dictionary.

   The wizard changes settings in your model depending on the configuration parameter Configuration Parameters > Diagnostics > Data Validity > Signal resolution.

   • If you set the parameter to Explicit only, the wizard forces the corresponding signals and states in your model to resolve to the new signal objects. The wizard selects the option Signal name must resolve to Simulink signal object in each Signal Properties dialog box and State name must resolve to Simulink signal object in each block dialog box.

   • If you set the parameter to Explicit and implicit or Explicit and warn implicit, the wizard does not change the setting of Signal name must resolve to Simulink signal object or State name must resolve to Simulink signal object for any signals or states.

   Consider turning off implicit signal object resolution for your model by using the function disableimplicitsignalresolution. For more information, see Explicit and Implicit Symbol Resolution.

Data Object Wizard Troubleshooting

• The Data Object Wizard compiles models for code generation in order to propose creation of signal objects. Because of this, the wizard cannot be used for models that are not valid for code generation.

• The Data Object Wizard does not propose creation of data objects for these entities in a model:

  • Multiple separate signals that have the same name.

  • A signal with the same name as a variable used in a block parameter.

  • A signal that lacks a single contiguous source block.

  • A signal whose source block is commented out or commented through.

  • Data items that are rendered inactive by Variant Source and Variant Sink blocks. The wizard proposes objects only for data items that are associated with active blocks.

  • Signals and states when you set the model configuration parameter Signal resolution to None.

Create Data Objects from External Data Source Programmatically

This example shows how to create data objects based on an external data source (such as a Microsoft^® Excel^® file) by using a script.

1. Create a new MATLAB script file.

2. Place information in the file that describes the data in the external file that you want to convert to data objects. For example, the following information creates two Simulink data objects with the indicated properties. The first is for a parameter and the second is for a signal:

   % Parameters
   ParCon = Simulink.Parameter;
   ParCon.CoderInfo.StorageClass = 'Custom'
   ParCon.CoderInfo.CustomStorageClass ='Const';
   ParCon.Value = 3;
   % Signals
   SigGlb = Simulink.Signal;
   SigGlb.DataType = 'int8';

3. Run the script file. The data objects appear in the MATLAB workspace.

If you want to import the target data from the external source, you can write MATLAB functions and scripts that read the information, convert the information to data objects, and load the objects into the base workspace.

You can use these functions to interact with files that are external to MATLAB:

• xmlread

• xmlwrite

• xlsread

• xlswrite

• csvread

• csvwrite

• dlmread

• dlmwrite

Data Object Methods

Data classes define functions, called methods, for creating and manipulating the objects that they define. A class may define any of the following kinds of methods.

Dynamic Methods

A dynamic method is a method whose identity depends on its name and the class of an object specified implicitly or explicitly as its first argument. You can use either function or dot notation to specify this object, which must be an instance of the class that defines the method or an instance of a subclass of the class that defines the method. For example, suppose class A defines a method called setName that assigns a name to an instance of A. Further, suppose the MATLAB workspace contains an instance of A assigned to the variable obj. Then, you can use either of the following statements to assign the name 'foo' to obj:

obj.setName('foo');
setName(obj, 'foo');

A class may define a set of methods having the same name as a method defined by one of its super classes. In this case, the method defined by the subclass overrides the behavior of the method defined by the parent class. Simulink determines which method to invoke at runtime from the class of the object that you specify as its first or implicit argument. Hence, the term dynamic method.

Note

Most Simulink data object methods are dynamic methods. Unless the documentation for a method specifies otherwise, you can assume that a method is a dynamic method.

Static Methods

A static method is a method whose identity depends only on its name and hence cannot change at runtime. To invoke a static method, use its fully qualified name, which includes the name of the class that defines it followed by the name of the method itself. For example, Simulink.ModelAdvisor class defines a static method named getModelAdvisor. The fully qualified name of this static method is Simulink.ModelAdvisor.getModelAdvisor. The following example illustrates invocation of a static method.

ma = Simulink.ModelAdvisor.getModelAdvisor('vdp');

Constructors

Every data class defines a method for creating instances of that class. The name of the method is the same as the name of the class. For example, the name of the Simulink.Parameter class's constructor is Simulink.Parameter. The constructors defined by Simulink data classes take no arguments.

The value returned by a constructor depends on whether its class is a handle class or a value class. The constructor for a handle class returns a handle to the instance that it creates if the class of the instance is a handle class; otherwise, it returns the instance itself (see Handle Versus Value Classes).

Handle Versus Value Classes

Simulink classes, including data object classes, fall into two categories: value classes and handle classes.

About Value Classes

The constructor for a value class (see Constructors) returns an instance of the class and the instance is permanently associated with the MATLAB variable to which it is initially assigned. Reassigning or passing the variable to a function causes MATLAB to create and assign or pass a copy of the original object.

For example, Simulink.NumericType is a value class. Executing the following statements

x = Simulink.NumericType;
y = x;

creates two instances of class Simulink.NumericType in the workspace, one assigned to the variable x and the other to y.

About Handle Classes

The constructor for a handle class returns a handle object. The handle can be assigned to multiple variables or passed to functions without causing a copy of the original object to be created. For example, Simulink.Parameter class is a handle class. Executing

x = Simulink.Parameter;
y = x;

creates only one instance of Simulink.Parameter class in the MATLAB workspace. Variables x and y both refer to the instance via its handle.

A program can modify an instance of a handle class by modifying any variable that references it, e.g., continuing the previous example,

x.Description = 'input gain';
y.Description

ans =
input gain

Most Simulink data object classes are value classes. Exceptions include Simulink.Signal and Simulink.Parameter class.

To determine whether the value of a variable is an object (value class) or a handle to an object, see Determine If an Object Is a Handle.

Copy Handle Objects

Use the copy method of a handle object to create copies of instances of that object. For example, ConfigSet is a handle object that represents model configuration sets. The following code creates a copy of the current model's active configuration set and attaches it to the model as an alternate configuration geared to model development.

activeConfig = getActiveConfigSet(gcs);
develConfig = copy(activeConfig);
develConfig.Name = 'develConfig';
attachConfigSet(gcs, develConfig);

Compare Data Objects

Simulink data objects provide a method, named isequal, that determines whether object property values are equal. This method compares the property values of one object with those belonging to another object and returns true (1) if all of the values are the same or false (0) otherwise. For example, the following code instantiates two signal objects (A and B) and specifies values for particular properties.

A = Simulink.Signal;
B = Simulink.Signal;
A.DataType = 'int8';
B.DataType = 'int8';
A.InitialValue = '1.5';
B.InitialValue = '1.5';

Afterward, use the isequal method to verify that the object properties of A and B are equal.

result = isequal(A,B)

result =

     1

Resolve Conflicts in Configuration of Signal Objects for Code Generation

If a signal is defined in the Signal Properties dialog box and a signal object of the same name is defined by using the command line or in the Model Explorer, the potential exists for ambiguity when the Simulink engine attempts to resolve the symbol representing the signal name. One way to resolve the ambiguity is to specify that a signal resolve to a Simulink.Signal data object. Select the Signal name must resolve to Simulink signal object option in the Signal Properties dialog box.

To configure the signal data, use the Code Mappings editor or code mappings API to add the signal to the model code mappings and set the storage class and storage class properties. For Simulink Coder™, see Configure Signal Data for C Code Generation (Simulink Coder). For Embedded Coder, see Configure Signal Data for C Code Generation (Embedded Coder).

Create Persistent Data Objects

To preserve data objects so that they persist when you close MATLAB, you can:

• Store the objects in a data dictionary or model workspace. To decide where to permanently store model data, see Determine Where to Store Variables and Objects for Simulink Models.

• Use the save command to save data objects in a MAT-file and the load command to restore them to the MATLAB base workspace in the same or a later session. Configure the model to load the objects from the MAT-file or a script file when the model loads.

To load data objects from a file when you load a model, write a script that creates the objects and configures their properties. Alternatively, save the objects in a MAT-file. Then use either the script or a load command as the PreLoadFcn callback routine for the model that uses the objects. Suppose that you save the data objects in a file named data_objects.mat, and the model to which they apply is open and active. At the command prompt, entering:

set_param(gcs, 'PreLoadFcn', 'load data_objects');

sets load data_objects as the model's preload function. Whenever you open the model, the data objects appear in the base workspace.

Definitions of the classes of saved objects must exist on the MATLAB path for them to be restored. If the class of a saved object acquires new properties after the object is saved, Simulink adds the new properties to the restored version of the object. If the class loses properties after the object is saved, only the properties that remain are restored.