Working with Data Objects :: Working with Data (Using Simulink)

Using Simulink

Working with Data Objects

Simulink allows you to create entities called data objects that specify values, data types, tunability, value ranges, and other key attributes of block outputs and parameters. You can assign such objects to workspace variables and 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. In other words, Simulink objects allow you to parameterize the specification of a model's data attributes.

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

Simulink allows you to create various types of data objects, each intended to be used to specify a particular type of data attribute or set of data attributes, such as a data item's type or value. The rest of this section describes features and procedures for working with data objects that apply to all data objects regardless of type. For information on working with specific kinds of data object, see the Data Object Classes section of the Simulink Reference.

About Data Object Classes

Simulink 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. Simulink provides a set of built-in classes for specifying specific types of attributes (see Data Object Classes for information on these built-in classes). Some MathWorks products based on Simulink, such as Real-Time Workshop, 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 Subclassing Simulink Data Classes).

Simulink uses memory structures called packages to store the code and data that implement data classes. The classes provided by Simulink 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. You can use either dot notation or function notation to invoke a method. For example, suppose class A defines a method called setName that assigns a name to an instance of A. Further, suppose the 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');

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

Using the Model Explorer to Create Data Objects

You can use the Model Explorer (see The Model Explorer) as well as MATLAB commands to create data objects. To use the Model Explorer , first select the workspace in which you want to create the object in the Model Explorer's Model Hierarchy pane.

Then, select the type of the object that you want to create (e.g., Simulink Parameter or Simulink Signal) from the Model Explorer's Add menu or from its toolbar. Simulink 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. Simulink searches the MATLAB path 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.

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 next topic) or MATLAB comands to change a data object's properties (see Using MATLAB Commands to Change an Object's Properties).

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 object's properties in the Contents pane (see Customizing the 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.DataType = '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.RTWInfo.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. Exececuting 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 evaluting 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)
        RTWInfo: [1x1 Simulink.ParamRTWInfo]
    Description: ''
       DocUnits: ''
            Min: -Inf
            Max: Inf
          Value: []
       DataType: 'auto'
     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';
attachActiveConfigSet(gcs, develConfig);

Saving and Loading Data Objects

You can use the MATLAB save command to save data objects in a MAT-file and the MATLAB 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, Simulink restores only the properties that remain.

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.

Typecasting Parameters Creating Persistent Data Objects