Store Data in Dictionary Programmatically

A data dictionary stores Simulink® model data and offers more data management features than the MATLAB® base workspace or the model workspace (see What Is a Data Dictionary?). To interact with the data in a dictionary programmatically:

  1. Create a Simulink.data.Dictionary object that represents the target dictionary.

  2. Create a Simulink.data.dictionary.Section object that represents the target section, for example the Design Data section. Use the object to interact with the entries stored in the section and to add entries.

  3. Optionally, create Simulink.data.dictionary.Entry objects that each represent an entry in the target section. Use these objects to interact with individual entries in the target section.

To programmatically access variables for the purpose of sweeping block parameter values, consider using Simulink.SimulationInput objects instead of modifying the variables through the programmatic interface of the data dictionary. See Optimize, Estimate, and Sweep Block Parameter Values.

To programmatically interact with the Embedded Coder section of a data dictionary, see Configure Code Definitions Programmatically (Embedded Coder).

Add Entry to Design Data Section of Data Dictionary

  1. Represent the Design Data section of the data dictionary myDictionary_ex_API.sldd with a Simulink.data.dictionary.Section object named dDataSectObj.

    myDictionaryObj = ...
    Simulink.data.dictionary.open('myDictionary_ex_API.sldd');
    dDataSectObj = getSection(myDictionaryObj,'Design Data');
    
  2. Add an entry to the Design Data section of myDictionary_ex_API.sldd an entry myNewEntry with value 237.

    addEntry(dDataSectObj,'myNewEntry',237)

Increment Value of Data Dictionary Entry

  1. Represent the data dictionary entry fuelFlow with a Simulink.data.dictionary.Entry object named fuelFlowObj. fuelFlow is defined in the data dictionary myDictionary_ex_API.sldd.

    myDictionaryObj = Simulink.data.dictionary.open('myDictionary_ex_API.sldd');
    dDataSectObj = getSection(myDictionaryObj,'Design Data');
    fuelFlowObj = getEntry(dDataSectObj,'fuelFlow');
  2. Store the value of the target entry in a temporary variable. Increment the value of the temporary variable by one.

    temp = getValue(fuelFlowObj);
    temp = temp+1;
  3. Set the value of the target entry by using the temporary variable.

    setValue(fuelFlowObj,temp)
    

Data Dictionary Management

Use Simulink.data.Dictionary objects to interact with entire data dictionaries.

GoalUse
Represent existing data dictionary with Simulink.data.Dictionary object

Simulink.data.dictionary.open

Create and represent data dictionary with Simulink.data.Dictionary object

Simulink.data.dictionary.create

Interact with data dictionary

Simulink.data.Dictionary class

Import variables to data dictionary from MATLAB base workspace

Simulink.data.Dictionary.importFromBaseWorkspace method

Add reference dictionary to a data dictionary

Simulink.data.Dictionary.addDataSource method

Remove reference dictionary from a data dictionary

Simulink.data.Dictionary.removeDataSource method

Save changes to data dictionary

Simulink.data.Dictionary.saveChanges method

Discard changes to data dictionary

Simulink.data.Dictionary.discardChanges method

View a list of entries stored in data dictionary

Simulink.data.Dictionary.listEntry method

Import enumerated type definitions to data dictionary

Simulink.data.Dictionary.importEnumTypes method

Return file name and path of data dictionary

Simulink.data.Dictionary.filepath method

Show data dictionary in Model Explorer window

Simulink.data.Dictionary.show method

Hide data dictionary from Model Explorer window

Simulink.data.Dictionary.hide method

Close connection between data dictionary and Simulink.data.Dictionary object

Simulink.data.Dictionary.close method

Identify data dictionaries that are open

Simulink.data.dictionary.getOpenDictionaryPaths

Close all connections to all open data dictionaries

Simulink.data.dictionary.closeAll

Dictionary Section Management

Data dictionaries store data as entries contained in sections, and by default all dictionaries have at least three sections named Design Data, Other Data, and Configurations. Use Simulink.data.dictionary.Section objects to interact with data dictionary sections.

GoalUse
Represent data dictionary section with Section object.

Simulink.data.Dictionary.getSection method

Interact with data dictionary section

Simulink.data.dictionary.Section class

Import variables to data dictionary section from MAT-file or MATLAB file

Simulink.data.dictionary.Section.importFromFile method

Export entries in data dictionary section to MAT-file or MATLAB file

Simulink.data.dictionary.Section.exportToFile method

Delete entry from data dictionary section

Simulink.data.dictionary.Section.deleteEntry method

Evaluate MATLAB expression in data dictionary section

Simulink.data.dictionary.Section.evalin method

Search for entries in data dictionary section

Simulink.data.dictionary.Section.find method

Determine whether entry exists in data dictionary section

Simulink.data.dictionary.Section.exist method

Dictionary Entry Manipulation

A variable that is stored in a data dictionary is called an entry of the dictionary. Entries have additional properties that store status information, such as the time and date the entry was last modified. Use Simulink.data.dictionary.Entry objects to manipulate data dictionary entries.

GoalUse
Represent data dictionary entry with Entry object

Simulink.data.dictionary.Section.getEntry method

Add data dictionary entry to section and represent with Entry object

Simulink.data.dictionary.Section.addEntry method

Manipulate data dictionary entry

Simulink.data.dictionary.Entry class

Assign new value to data dictionary entry

Simulink.data.dictionary.Entry.setValue method

Display changes made to data dictionary entry

Simulink.data.dictionary.Entry.showChanges method

Save changes made to data dictionary

Simulink.data.Dictionary.saveChanges method

Discard changes made to data dictionary entry

Simulink.data.dictionary.Entry.discardChanges method

Search in an array of data dictionary entries

Simulink.data.dictionary.Entry.find method

Return value of data dictionary entry

Simulink.data.dictionary.Entry.getValue method

Delete data dictionary entry

Simulink.data.dictionary.Entry.deleteEntry method

Store enumerated type definition in dictionary

Simulink.data.dictionary.EnumTypeDefinition class

Transition to Using Data Dictionary

Using a data dictionary can complicate programmatic interaction with model data. If you link a model to a dictionary:

  • You can no longer interact with the model data by using simple commands at the command prompt. Instead, you must use the programmatic interface of the dictionary (Simulink.data.Dictionary).

  • When you select the dictionary property Enable access to base workspace (see Continue to Use Shared Data in the Base Workspace), depending on the storage location of the target data, you must use either simple commands or the programmatic interface.

To help transition from using the base workspace to using data dictionaries, consider using these functions. The functions operate on model data regardless of the storage location of the data.

GoalUse
Change value of data dictionary entry or workspace variable in context of Simulink model

Simulink.data.assigninGlobal

Evaluate MATLAB expression in context of Simulink model

Simulink.data.evalinGlobal

Determine existence of data dictionary entry or workspace variable in context of Simulink model

Simulink.data.existsInGlobal

Programmatically Migrate Single Model to Use Dictionary

To change the data source of a Simulink model from the MATLAB base workspace to a new data dictionary, use this example code as a template.

% Define the model name and the data dictionary name
modelName = 'f14';
dictionaryName = 'myNewDictionary.sldd';

% Load the target model
load_system(modelName);

% Identify all model variables that are defined in the base workspace
varsToImport = Simulink.findVars(modelName,'SourceType','base workspace');
varNames = {varsToImport.Name};

% Create the data dictionary
dictionaryObj = Simulink.data.dictionary.create(dictionaryName);

% Import to the dictionary the model variables defined in the base
% workspace, and clear the variables from the base workspace
[importSuccess,importFailure] = importFromBaseWorkspace(dictionaryObj,...
    'varList',varNames,'clearWorkspaceVars',true);

% Link the dictionary to the model
set_param(modelName,'DataDictionary',dictionaryName);

Note

This code does not migrate the definitions of enumerated data types that were used to define model variables. If you import model variables of enumerated data types to a data dictionary but do not migrate the enumerated type definitions, the dictionary is less portable and might not function properly if used by someone else. To migrate enumerated data type definitions to a data dictionary, see Enumerations in Data Dictionary.

Import Directly From External File to Dictionary

This example shows how to use a custom MATLAB function to import data directly from an external file to a data dictionary without creating or altering variables in the base workspace.

  1. Create a two-dimensional lookup table in one sheet of a Microsoft® Excel® workbook. Use the upper-left corner of the sheet to provide names for the two breakpoints and for the table. Use column B and row 2 to store the two breakpoints, and use the rest of the sheet to store the table. For example, your lookup table might look like this:

    Save the workbook in your current folder as my2DLUT.xlsx.

  2. Copy this custom function definition into a MATLAB file, and save the file in your current folder as importLUTToDD.m.

    function importLUTToDD(workbookFile,dictionaryName)
        % IMPORTLUTTODD(workbookFile,dictionaryName) imports data for a
        % two-dimensional lookup table from a workbook directly into a data
        % dictionary. The two-dimensional lookup table in the workbook can be
        % any size but must follow a standard format.
    
        % Read in the entire first sheet of the workbook.
        [data,names,~] = xlsread(workbookFile,1,'');
    
        % Divide the raw imported data into the breakpoints, the table, and their
        % names.
        % Assume breakpoint 1 is in the first column and breakpoint 2 is in the
        % first row.
        % Assume cells A2, B1, and B2 define the breakpoint names and table name.
        bkpt1 = data(2:end,1);
        bkpt2 = data(1,2:end);
        table = data(2:end,2:end);
        bkpt1Name = names{2,1};
        bkpt2Name = names{1,2};
        tableName = names{2,2};
    
        % Prepare to import to the Design Data section of the target data
        % dictionary.
        myDictionaryObj = Simulink.data.dictionary.open(dictionaryName);
        dDataSectObj = getSection(myDictionaryObj,'Design Data');
    
        % Create entries in the dictionary to store the imported breakpoints and
        % table. Name the entries using the breakpoint and table names imported
        % from the workbook.
        addEntry(dDataSectObj,bkpt1Name,bkpt1);
        addEntry(dDataSectObj,bkpt2Name,bkpt2);
        addEntry(dDataSectObj,tableName,table);
    
        % Save changes to the dictionary and close it.
        saveChanges(myDictionaryObj)
        close(myDictionaryObj)
    
  3. At the MATLAB command prompt, create a data dictionary to store the lookup table data.

    myDictionaryObj = Simulink.data.dictionary.create('myLUTDD.sldd');
  4. Call the custom function to import your lookup table to the new data dictionary.

    importLUTToDD('my2DLUT.xlsx','myLUTDD.sldd')
  5. Open the data dictionary in Model Explorer.

    show(myDictionaryObj)

    Three new entries store the imported breakpoints and lookup table. These entries are ready to use in a 2-D Lookup Table block.

Programmatically Partition Data Dictionary

To partition a data dictionary into reference dictionaries, use this example code as a template. You can use reference dictionaries to make large data dictionaries more manageable and to contain standardized data that is useful for multiple models.

% Define the names of a parent data dictionary and two
% reference data dictionaries
parentDDName = 'myParentDictionary.sldd';
typesDDName = 'myTypesDictionary.sldd';
paramsDDName = 'myParamsDictionary.sldd';

% Create the parent data dictionary and a
% Simulink.data.Dictionary object to represent it
parentDD = Simulink.data.dictionary.create(parentDDName);

% Create a Simulink.data.dictionary.Section object to represent 
% the Design Data section of the parent dictionary
designData_parentDD = getSection(parentDD,'Design Data');

% Import some data to the parent dictionary from the file partDD_Data_ex_API.m
importFromFile(designData_parentDD,'partDD_Data_ex_API.m');

% Create two reference dictionaries
Simulink.data.dictionary.create(typesDDName);
Simulink.data.dictionary.create(paramsDDName);

% Create a reference dictionary hierarchy by adding reference dictionaries 
% to the parent dictionary
addDataSource(parentDD,typesDDName);
addDataSource(parentDD,paramsDDName);

% Migrate all Simulink.Parameter objects from the parent data dictionary to
% a reference dictionary
paramEntries = find(designData_parentDD,'-value','-class','Simulink.Parameter');
for i = 1:length(paramEntries)
    paramEntries(i).DataSource = 'myParamsDictionary.sldd';
end

% Migrate all Simulink.NumericType objects from the parent data dictionary
% to a reference dictionary
typeEntries = find(designData_parentDD,'-value','-class','Simulink.NumericType');
for i = 1:length(typeEntries)
    typeEntries(i).DataSource = 'myTypesDictionary.sldd';
end

% Save all changes to the parent data dictionary
saveChanges(parentDD)

Make Changes to Configuration Set Stored in Dictionary

You can store a configuration set (a Simulink.ConfigSet object) in the Configurations section of a dictionary. To change the setting of a configuration parameter in the set programmatically:

  1. Create a Simulink.data.dictionary.Entry object that represents the configuration set (which is an entry in the dictionary). For example, suppose the name of the dictionary is myData.sldd and the name of the Simulink.ConfigSet object is myConfigs.

    dictionaryObj = Simulink.data.dictionary.open('myData.sldd');
    configsSectObj = getSection(dictionaryObj,'Configurations');
    entryObj = getEntry(configsSectObj,'myConfigs');

  2. Store a copy of the target Simulink.ConfigSet object in a temporary variable.

    temp = getValue(entryObj);

  3. In the temporary variable, modify the target configuration parameter (in this case, set Stop time to 20).

    set_param(temp,'StopTime','20');

  4. Use the temporary variable to overwrite the configuration set in the dictionary.

    setValue(entryObj,temp);

  5. Save changes made to the dictionary.

    saveChanges(dictionaryObj)

See Also

| | |

Related Topics