Data Objects

About Data Object Classes

You can create entities called data objects that specify values, data types, tunability, value ranges, and other key attributes of block outputs and parameters. You can create various types of data objects and assign them to workspace variables. You can use the variables in Simulink® dialog boxes to specify parameter and signal attributes. This allows you to make model-wide changes to parameter and signal specifications simply by changing the values of a few variables. With Simulink objects you can parameterize the specification of a model's data attributes.

    Note   This section uses the term data to refer generically to signals and parameters.

The Simulink software uses objects called data classes to define the properties of specific types of data objects. The classes also define functions, called methods, for creating and manipulating instances of particular types of objects. A set of built-in classes are provided for specifying specific types of attributes. Some MathWorks® products based on Simulink, such as the Simulink Coder™ product, also provide classes for specifying data attributes specific to their applications. See the documentation for those products for information on the classes they provide. You can also create subclasses of some of these built-in classes to specify attributes specific to your applications (see Define Data Classes).

Memory structures called packages are used to store the code and data that implement data classes. The classes provided by the Simulink software reside in the Simulink package. Classes provided by products based on Simulink reside in packages provided by those products. You can create your own packages for storing the classes that you define.

Class Naming Convention

Simulink uses dot notation to name classes:

PACKAGE.CLASS

where CLASS is the name of the class and PACKAGE is the name of the package to which the class belongs, for example, Simulink.Parameter. This notation allows you to create and reference identically named classes that belong to different packages. In this notation, the name of the package is said to qualify the name of the class.

    Note   Class and package names are case sensitive. You cannot, for example, use A.B and a.b interchangeably to refer to the same class.

About 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. The Simulink software 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).

Create Data Objects Using Model Explorer

This example shows how to create data objects using Model Explorer.

Open the Model Explorer. In the Simulink Editor, select View > Model Explorer.

In the Model Hierarchy pane, select Base Workspace.

Click Add > Simulink Parameter

A Simulink.Parameter object appears in the base workspace with its properties displayed in the Model Properties pane.

Using the Model Explorer to Create Data Objects

You can use the Model Explorer (see Model Explorer Overview) as well as MATLAB commands to create data objects. To use the Model Explorer,

  1. Select the workspace in which you want to create the object in the Model Explorer Model Hierarchy pane.

    Only Simulink.Parameter and Simulink.Signal objects for which the storage class is set to Auto can reside in a model workspace. You must create all other Simulink data objects in the base MATLAB workspace to ensure the objects are unique within the global Simulink context and accessible to all models.

      Note:   Subclasses of Simulink.Parameter and Simulink.Signal classes, including mpt.Parameter and mpt.Signal objects (Embedded Coder® license required), can reside in a model workspace only if their storage class is set to Auto.

  2. Select the type of the object that you want to create (for example, Simulink Parameter or Simulink Signal) from the Model Explorer's Add menu or from its toolbar. The Simulink software creates the object, assigns it to a variable in the selected workspace, and displays its properties in the Model Explorer's Contents and Dialog panes.

    If the type of object you want to create does not appear on the Add menu, select Find Custom from the menu. The MATLAB path is searched for all data object classes derived from Simulink class on the MATLAB path, including types that you have created, and displays the result in a dialog box.

  3. Select the type of object (or objects) that you want to create from the Object class list and enter the names of the workspace variables to which you want the objects to be assigned in the Object name(s) field. Simulink creates the specified objects and displays them in the Model Explorer's Contents pane.

About Object Properties

Object properties are variables associated with an object that specify properties of the entity that the object represents, for example, the size of a data type. The object's class defines the names, value types, default values, and valid value ranges of the object's properties.

Changing Object Properties

You can use either the Model Explorer (see Using the Model Explorer to Change an Object's Properties) or MATLAB commands to change a data object's properties (see Use MATLAB Commands to Change Workspace Data).

Using 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: Contents Pane). 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.

Using 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';

Handle Versus Value Classes

Simulink 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.

You can determine whether a variable is assigned to an instance of a class or to a handle to that class by evaluating it at the MATLAB command line. MATLAB appends the text (handle) to the name of the object class in the value display, e.g.,

>> gain = Simulink.Parameter
 
gain =

Simulink.Parameter (handle)
          Value: []
        CoderInfo: [1x1 Simulink.ParamCoderInfo]
    Description: ''
       DataType: 'auto'
            Min: []
            Max: []
       DocUnits: ''
     Complexity: 'real'
     Dimensions: [0 0]

Copying Handle Classes

Use the copy method of a handle class to create copies of instances of that class. For example, Simulink.ConfigSet is a handle class 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 = activeConfig.copy;
develConfig.Name = 'develConfig';
attachConfigSet(gcs, develConfig);

Comparing 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 = A.isequal(B)

result =

     1

Saving and Loading Data Objects

You can use the save command to save data objects in a MAT-file and the load command to restore them to the MATLAB workspace in the same or a later session. 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.

Using Data Objects in Simulink Models

You can use data objects in Simulink models as parameters and signals. Using data objects as parameters and signals allows you to specify simulation and code generation options on an object-by-object basis.

Creating Persistent Data Objects

To create parameter and signal objects that persist across Simulink sessions, first write a script that creates objects (see Define Data Classes) or at the command line and save them in a MAT-file (see Saving and Loading Data Objects). Then use either the script or a load command as the PreLoadFcn callback routine for the model that uses the objects. For example, suppose you save the data objects in a file named data_objects.mat and the model to which they apply is open and active. Then, entering the following command

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

at the MATLAB command line sets load data_objects as the model's preload function. This in turn causes the data objects to be loaded into the model workspace whenever you open the model.

Data Object Wizard

The Data Object Wizard allows you to determine quickly which model data are not associated with data objects and to create and associate data objects with the data.

  1. In the Simulink Editor, select Code > Data Objects > Data Object Wizard.

    The Data Object Wizard appears.

  2. Enter, if necessary, the name of the model you want to search in the wizard's Model name field.

    By default the wizard displays the name of the model from which you opened the wizard. You can enter the name of another model in this field. If the model is not open, the wizard opens the model.

  3. In Find options, uncheck any of the data object types that you want the search to ignore.

    The search options include:

    OptionDescription
    Root inputsNamed signals from root-level input ports
    Root outputsNamed signals from root-level output ports
    States

    States associated with any instances of the following discrete block types:

    Discrete Filter
    Discrete State-Space
    Discrete-Time Integrator
    Discrete Transfer Fcn
    Discrete Zero-Pole
    Memory
    PID Controller
    PID Controller (2DOF)
    Unit Delay
    Data storesData stores (see About Data Stores )
    Block outputsNamed signals emitted by non-root-level blocks.
    Parameters
    Alias typesData whose data type is a registered custom data type. This option applies only if you are generating code from the model. See Create Data Objects with Data Object Wizard in the Embedded Coder documentation for more information.

  4. Click the wizard's Find button.

    The wizard displays the search results in the data objects table.

  5. Select the data for which you want the wizard to create data objects.

  6. If you want the wizard to use data object classes from a package other than the Simulink standard class package to create the data objects, select the package from the Choose package for selected data objects list and then select Apply Package to confirm your choice.

      Note:   User-defined packages that you add to the Data Object Wizard must contain a Simulink.Signal subclass named Signal and a Simulink.Parameter subclass named Parameter.

  7. Click Create.

    The wizard creates data objects of the appropriate class for the data selected in the search results table.

    The setting of Signal resolution for your model in Model Configuration Parameters > Diagnostics > Data Validity.

    • If this parameter is defined as Explicit, the wizard sets signals in your model to resolve to a signal object.

    • If this parameter is defined as Explicit and implicit or Explicit and warn implicit, the wizard does not set Must resolve to signal object for signals.

    Consider turning off implicit signal object resolution for your model using disableimplicitsignalresolution.

  8. Check the setting of Signal resolution for your model in Model Configuration Parameters > Diagnostics > Data Validity.

    • If this parameter is defined as Explicit, the wizard sets signals in your model to resolve to a signal object.

    • If this parameter is defined as Explicit and implicit or Explicit and warn implicit, the wizard does not set signals in your model to resolve to signal objects.

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

  9. Use the Model Explorer to view and edit the created data objects.

Was this topic helpful?