Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

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 to specify the Gain parameter of a Gain block:

  1. Create a parameter object. For example, create an object using the built-in package Simulink.

    myParam = Simulink.Parameter;
    

  2. Assign a numeric value to the Value property.

    myParam.Value = 15.23;

  3. 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 Min and Max properties.

    myParam.Min = 10.11;
    myParam.Max = 25.27;

  4. In a block dialog box, specify the value of a parameter as myParam. For example, in a Gain block dialog box, specify Gain as myParam.

    During simulation, the Gain parameter 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. Create a Simulink.Signal object. For example, create an object using the built-in package Simulink.

    mySig = Simulink.Signal;

  2. Specify the signal characteristics by adjusting the object properties. For example, to specify the signal data type as boolean, use the DataType object property.

    mySig.DataType = 'boolean';

  3. In the Signal Properties dialog box for the signal in the model, specify Signal name as mySig. Click Apply.

  4. Select the check box next to Signal name must resolve to Simulink signal object.

    This option forces the model signal to use the properties that the signal object mySig defines. To learn how to control the way that signal names resolve to signal objects, see Symbol Resolution.

    If you do not see the option in the Signal Properties dialog box, set the model configuration parameter Configuration Parameters > Diagnostics > Data Validity > Signal resolution to a value other than None.

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

You can also use a signal object to control the characteristics of a root-level Outport block. To interactively associate the block with a signal object, you must use the Model Data Editor (see Configure Data Properties by Using a Table):

  1. Set the Change View drop-down list to Code.

  2. Apply a name to the Outport block by using the Signal Name column.

  3. Select the box in the Resolve column.

To configure the block programmatically:

% 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. Create a Simulink.Signal object. For example, create an object using the built-in package Simulink.

    myState = Simulink.Signal;

  2. Specify the state characteristics by adjusting the object properties. For example, to specify the state data type as int16, use the DataType object property.

    myState.DataType = 'int16';

  3. In a block dialog box, on the State Attributes tab, specify State name as myState. Click Apply.

  4. Select the check box next to State name must resolve to Simulink signal object.

    If you do not see this option on the State Attributes tab, set the model configuration parameter Configuration Parameters > Diagnostics > Data Validity > Signal resolution to a value other than None.

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

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, select Add > Add Custom.

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 custom 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 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 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 or a block dialog box, 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 Variable.

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

  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.

  6. In the Signal Properties dialog box, select the check box next to Signal name must resolve to Simulink signal object and click OK.

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, select Code > Data Objects > 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.

    OptionDescription
    Root inputsNamed signals from root-level Inport blocks.
    Root outputsNamed 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
    PID Controller
    PID Controller (2DOF)
    Unit Delay
    Data storesData stores. For more information about data stores, see Local and Global Data Stores .
    Block outputsNamed signals whose sources are non-root-level blocks.
    Parameters
    Alias typesData 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 Data Type Replacement (Embedded Coder) in the Embedded Coder documentation.

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

You can determine whether a variable is assigned to an instance of a class or to a handle to that class by displaying the variable 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.CoderInfo]
    Description: ''
       DataType: 'auto'
            Min: []
            Max: []
           Unit: ''
     Complexity: 'real'
     Dimensions: [0 0]

Copy 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 = 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

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.

See Also

| | | |

Related Topics

Was this topic helpful?