Store Data in Dictionary Programmatically - MATLAB & Simulink (original) (raw)

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

For most common data management tasks, regardless of data source, you can use theSimulink.data.connect function to create a connection to your data source, then use the common set of functions provided by the Simulink.data.DataConnection object. For more information, see Manage Design Data for Simulink Models Programmatically.

For tasks specific to a data dictionary, use aSimulink.data.Dictionary object:

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 Create Data Interface Configuration Programmatically (Embedded Coder).

To programmatically interact with the Architectural Data section of a data dictionary, see Store Data in Architectural Data Section Programmatically.

Add Entry to Design Data Section of Data Dictionary

1. Represent the Design Data section of the data dictionarymyDictionary_ex_API.sldd with aSimulink.data.dictionary.Section object nameddDataSectObj.
   myDictionaryObj = Simulink.data.dictionary.open('myDictionary_ex_API.sldd');
   dDataSectObj = getSection(myDictionaryObj,'Design Data');
2. In the Design Data section ofmyDictionary_ex_API.sldd, add entrymyNewEntry with value237.
   addEntry(dDataSectObj,'myNewEntry',237)

Rename Data Dictionary Entry

Rename an entry in the Design Data, Configurations, or Other Data section of a data dictionary.

1. Represent the data dictionary entry fuelFlow with aSimulink.data.dictionary.Entry object namedfuelFlowObj. fuelFlow is defined in the data dictionarymyDictionary_ex_API.sldd.
   myDictionaryObj = Simulink.data.dictionary.open('myDictionary_ex_API.sldd');
   dDataSectObj = getSection(myDictionaryObj,'Design Data');
   fuelFlowObj = getEntry(dDataSectObj,'fuelFlow');
2. Rename the data dictionary entry.
   fuelFlowObj.Name = 'fuelFlowNew';

Increment Value of Data Dictionary Entry

1. Represent the data dictionary entry fuelFlow with aSimulink.data.dictionary.Entry object namedfuelFlowObj. fuelFlow is defined in the data dictionarymyDictionary_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)

Manage Configuration Set Stored in Data Dictionary

Change configuration parameter values in a configuration set stored in the Configurations section of a data dictionary.

1. Open the data dictionary.
   dd = Simulink.data.dictionary.open('my_sldd.sldd')
2. Get the Configurations section of the dictionary.
   ds = dd.getSection('Configurations')
3. List available configuration sets.
   ds.find('-class','Simulink.data.dictionary.Entry')
   Alternatively, find specific configuration sets by using a regular expression.
   ds.find('-regexp','Name','C*')
4. Get a local copy of a configuration set.
   cs1=ds.getEntry('Configuration1')
   v1=cs1.getValue()
5. Change the setting of a configuration parameter in the local copy of the configuration set.
   set_param(v1,'SystemTargetFile','grt.tlc')
6. Push the changed configuration set back into the data dictionary.
7. Save the changes to the data dictionary.

Data Dictionary Management

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

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.

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. UseSimulink.data.dictionary.Entry objects to manipulate data dictionary entries.

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

Programmatically Migrate Single Model to Use Dictionary

This example shows how to programmatically change the data source of a Simulink model from the base workspace to a new data dictionary.

% Define 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 that 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 asmy2DLUT.xlsx.
2. Copy this custom function definition into a MATLAB file, and save the file in your current folder asimportLUTToDD.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.
   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 ismyData.sldd and the name of theSimulink.ConfigSet object ismyConfigs.
   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 to20).
   set_param(temp,'StopTime','20');
4. Use the temporary variable to overwrite the configuration set in the dictionary.
5. Save changes made to the dictionary.
   saveChanges(dictionaryObj)

See Also

Simulink.findVars | set_param | Simulink.data.dictionary.setupWorkerCache | Simulink.data.dictionary.cleanupWorkerCache | Simulink.data.DataConnection | Simulink.data.connect

Topics

• Enumerations in Data Dictionary
• Migrate Model Reference Hierarchy to Use Dictionary
• What Is a Data Dictionary?
• Optimize, Estimate, and Sweep Block Parameter Values
• Manage Design Data for Simulink Models Programmatically