Once again I wish to welcome guest blogger Donn Shull. Donn has previously written a series of articles on Matlab’s previous-generation class-object system (UDD). Today Donn explores a little-known yet quite useful aspect of Simulink.
Introduction
In 2014, MathWorks introduced the Simulink Data Dictionary. This new feature provides the ability to store Data Types, Parameters, and Signals in database files. This is great news for embedded systems developers who want the flexibility of using data objects and want to avoid using the base workspace with its potential for data corruption.
In its initial implementation, the data dictionary interface is provided by the Simulink Model Explorer. The GUI interface is clean, intuitive, and easy to use. This interface supports importing and exporting dictionaries to m files and mat files.
Unfortunately, in production code generation environments there is frequently a need to interface this data with external tools such as software specification systems, documentation generators, and calibration tools. MathWorks have not published an API for accessing dictionaries from code, indicating that it may possibly be available in a future release. Today, we will look at some portions of the undocumented API for Simulink Data Dictionaries.
Some background information
Simulink Data Dictionaries exist as files having a standard file extension of .sldd. Dictionary files can be opened with the open function, which in turn calls opensldd. This opens the file and launches the Simulink Model Explorer with the selected dictionary node. When a dictionary is opened, a cached copy is created. While working with a dictionary, changes are made to the cached copy. The dictionary file is only changed when the changes are saved by issuing the relevant command. Until the cached copy is saved, it is possible to view differences between the file and the cached copy, and revert any unwanted changes. The file maintains the date, time, and author of the last saved change, but no information about previous revisions.
From the Model Explorer it is possible to add items to a dictionary from a model, the base workspace, or by creating new items. We can associate a Simulink model with a dictionary by using the model properties dropdown in the Simulink editor.
Using data dictionaries it is possible to tailor a model’s code generation for different targets, simply by changing the dictionary that is being used.
The Simulink Data Dictionary API
Programmatic access to Simulink Data Dictionaries is provided by the undocumented MCOS package Simulink.dd. We will look at two package functions and a few methods of the Simulink.dd.Connection class. These provide the basic ability to work with dictionaries from within our m code.
Creating and Opening Dictionary Files
Dictionary files are created with the package function create:
hDict = Simulink.dd.create(dictionaryFileName); |
Existing dictionary files are opened using the package function open:
hDict = Simulink.dd.open(dictionaryFileName); |
In both cases the functions return a handle of type Simulink.dd.Connection to the named dictionary file.
Modifying a Dictionary
We can use methods of the Simulink.dd.Connection instance to modify an open dictionary. Dictionaries are organized into two sections: The Configurations section contains Simulink.ConfigSet entries, while Parameter, Signal, and DataType items are placed in the Global section. We can get a list of the items in a section using the getChildNames method:
childNamesList = hDict.getChildNames(sectionName); |
Adding and removing items from a section are done using the insertEntry and deleteEntry methods, respectively:
hDict.insertEntry(sectionName, entryName, object) hDict.deleteEntry(sectionName, entryName) |
Modifying an existing entry is done using the getEntry, and setEntry methods:
workingCopy = hDict.getEntry(sectionName.entryName) % modify workingCopy hDict.setEntry(sectionName.entryName, workingCopy) |
A collection of objects from the base workspace can be added to a dictionary using the importFromBaseWorkspace method:
hDict.importFromBaseWorkspace(sectionName, overwriteExisitngObjectsFlag, deleteFromBaseWorkspaceFlag, cellArrayOfNames) |
Additional dictionary manipulations are possible using the evalin and assignin methods:
hDict.evalin(commandString) hDict.assignin(variableName, variable) |
Closing a Dictionary
Finalizing a dictionary session is done with the saveChanges, close, and delete methods:
hDict.saveChanges hDict.close hDict.delete |
Example: Migrate Single Model to Use Dictionary
This example is an adaptation of MathWorks’ interactive example of the same title, using programmatic Matlab commands rather than GUI interactions.
- Start by using load_system to open the f14 model. This opens the model and executes the PreLoadFcn callback, which loads design data into the base workspace, without opening the Simulink block diagram editor:
load_system('f14');
- Use the Simulink package function findVars to find the variables used by the model:
usedVariables = Simulink.findVars('f14');
- Next, use the create package function to create and open a new Simulink Data Dictionary:
hDict = Simulink.dd.create('f14_data_dictionary.sldd');
- Attach the newly created dictionary to the model:
set_param('f14', 'DataDictionary', 'f14_data_dictionary.sldd');
- Use one of the API methods to add these variables to the Data Dictionary:
overWrite = true; deleteFromWorkspace = false; for n = 1:numel(usedVariables) if strcmp(usedVariables(n).Source, 'base workspace') hDict.importFromBaseWorkspace(overWrite, deleteFromWorkspace, {usedVariables(n).Name}); end end
- Save the changes made to the dictionary:
hDict.saveChanges; - Clean up and we are done:
hDict.close; hDict.delete; clear hDict;
Final notes
MathWorks have recognized the value of data dictionaries for a long time. In 2006, MathWorker Tom Erkkinen published a paper about multitarget modeling using data dictionaries. The Simulink.dd package was added to Matlab in R2011b, and the DataDictionary parameter was added to Simulink models in R2012a. MathWorks have also indicated that a user API for Simulink Data Dictionaries may be in the works. Until it is released we can make do with the undocumented API.
Update March 7, 2015: Matlab release R2015a now includes a fully documented Simulink.data.Dictionary class, which works in a very similar manner. Users of R2015a or newer should use this new Simulink.data.Dictionary class, while users of previous Matlab releases can use the Simulink.dd class presented in this article.
Have you made some good use of this data-dictionary functionality in your project? If so, please share your experience in a comment below.
Hey Donn,
thanks for that small tutorial. I am currently working with data dictionaries and access them via Matlab. Unfortunately, no API documentation is published from Mathworks. Thus, your article is one of the only Information about data dict and API I have.
I am trying with the assignin and evalin command. I am not getting along with it. Could you please provide a small example?
Do you have additional API commands or do you know any sources where I can find them?
All the best and thanks for any help.
Florian
Hi Florian,
There is an error in my API documentation above. Both assignin and evalin work in the ‘Global’ section and the API and the sectionName in the argument list is wrong. The correct syntax is:
These API commands were from my own research in working with the model explorer. I don’t know of any other sources. Note that Yair posted about this article on MATLAB Answers. The MathWorks responded and indicated that a future release will have a documented API and it will probably be different than this API.
I’ve updated the article text accordingly
Hi Donn,
there is already a documentation of the API in the current pre-release of Matlab 2015a. 🙂
I’ve one question concerning Data Dictionaries in model reference hierarchies:
Is it mandatory that every parent model needs a reference in its data dictionary to each of its referenced models? (This question is also posted in Matlab Answers)
Thanks for any help.
Hi Florian,
I am not sure I understand why you would not want to have a matching dictionary hierarchy for a given model hierarchy. The syntax is very simple:
In any event it seems like the best way to see if it is mandatory would be to run simulations, and generate code each way and check your results.
Update:
R2015a has a documented API for the Simulink Data Dictionary. It is based around the Simulink.dataDictionary class. This class was first introduced in R2014b, and at first glance hte R2015a documentation applies to R2014b. If you are using R2014a you will need to use the undocumented Simulink.dd.Connection described here.
Hey Donn,
Configuration: Matlab 2015b
Background: I’m working with a large project and we initially decided to put all “variables” into the Simulink Data Dictionary. The API is documented enough so I can programmatically access all of the features I need. Because the only built-in graphical interface for the Simulink Data Dictionary is the Model Explorer, I have found that the workflow is very slow when implementing an algorithm in Simulink. I’ve got to constantly flip between the Model Explorer and the Simulink Model. It’s very annoying. Without going into any details, our team decided to create our own GUI to interface between the Simulink Data Dictionary and the Simulink Model to avoid having to open the Model Explorer.
My Problem: To test the GUI, I’ve created a dummy Simulink Data Dictionary to be about 2 times larger than what I expect the end result will be. The DD I created has about 55K entries in it and I’m finding that the DDEntry class is extremely slow. It’s taking about 135 seconds (according to the profiler) to just read the names of each entry and load them into a cell array (to be used later by the GUI). I have files and examples I could send to you if it would help.
Thanks for any help,
Dave
Hello Dave,
I apologize for the lateness of the response. Somehow I missed your question when you first posted it. I hope you have found solutions to your problems. As far as I know the fastest way to get a list of the names of the entries in a Simulink Data Dictionary is to use the ‘who’ command:
I hope this helps.
Donn
Hi Dave,
One further note. To open the pop-up dialog for a data dictionary entry named entryName programmatically you can use:
Donn
Something I ran into recently was a need to provide runtime initialization of Simulink data parameter objects in a compiled application. I solved the issue by calling a config file parser in the hand coded portion of the models initialization function, and used the C-API interface to update the model parameters to match the values specified in the config file, but I really wanted to simply load a Simulink Data Dictionary instead as it seemed a very obvious use for them.
Have there been any hints of data dictionaries being natively usable in compiled models for anything besides compile-time initialization of data objects?
Hi Matt,
To my knowledge the answer is no. In the automotive world there is a system for doing what you describe. It is fairly complex and based around a closed set of standards from the group “Association for Standardisation of Automation and Measuring Systems”. You can read about the group at http://asam.net. One of the motivations for the creation of Simulink Data Objects and the Simulink Data Dictionary was to support the creation of ASAP2 variable description files. These ASAM ASAP2 files along with ASAM CDF (Calibration Data Format) files provide the mechanism that calibration engineers use to read measurements from an embedded control system and to do the thing you describe providing initial values for constants and tuning values of other constants during operation.
The idea that you propose is interesting rather than parsing a config file it would be nice to use api commands to extract the values from a data dictionary file. I am not sure why The MathWorks has kept the Data Dictionary implementation under wraps. It seems very likely that under the hood it is very likely an embedded database along the lines of MySql Embedded or SqLite. If you could get that information from The MathWorks then it seems that it would be reasonably easy to do what you are asking.
If you find out more please let us know.
Donn
Can anybody tell me that how i can import .dd (Data dictionary) file in MATLAB and then import the properties of dd file to matlab?
I would need more information to help you. Simulink Data Dictionary files (.sldd) files are covered in many places. What is the format of the Data dictionary files (.dd) you are referring to?
Can anyone let me know if there is an option to give comments or annotations inside the datadictionary. At present, the variables listed in the dictionary does not seem to have such option. Please give if any
@Kanthaswamy – perhaps you can run
struct(Simulink.data.Dictionary)or use my getundoc utility to check whether there are any hidden properties that you can use to store your comments/annotations.Hi,
Is there a way to test if data dictionnatry entry are signal, simulink parameters, variables …
I need to access their value, but the access method depends on the data type into the dictionary
Perhaps the
class()function could assist you. Or maybe just wrap different access methods in atry-catchso that if one method fails you could access the data using another method.Hello,
I would like to add a new object into SLDD and display columns according to my object properties
<>