Simulink Data Dictionary

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.

Simulink F14 model using data dictionary

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 m commands rather than GUI interactions.

  1. 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');
  2. Use the Simulink package function findVars to find the variables used by the model:
    usedVariables = Simulink.findVars('f14');
  3. Next, use the create package function to create and open a new Simulink Data Dictionary:
    hDict = Simulink.dd.create('f14_data_dictionary.sldd');
  4. Attach the newly created dictionary to the model:
    set_param('f14', 'DataDictionary', 'f14_data_dictionary.sldd');
  5. 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
  6. Save the changes made to the dictionary:
    hDict.saveChanges;
  7. 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.

Categories: Guest bloggers, Medium risk of breaking in future versions, Stock Matlab function, Undocumented feature

Tags: , , , ,

Bookmark and SharePrint Print

9 Responses to Simulink Data Dictionary

  1. Florian says:

    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

    • Donn Shull says:

      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:

      hDict.evalin(commandString)
      hDict.assignin(variableName, variable)

      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

  2. Florian says:

    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.

    • Donn Shull says:

      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:

      parent = Simulink.dd.open('parent.sldd');
      parent.addReference('child.sldd');

      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.

  3. Donn Shull says:

    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.

  4. David Bellairs says:

    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

    • Donn Shull says:

      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:

      nameList = hDictionary.getSection('Global').evalin('who');

      I hope this helps.

      Donn

    • Donn Shull says:

      Hi Dave,

      One further note. To open the pop-up dialog for a data dictionary entry named entryName programmatically you can use:

      DAStudio.Dialog(hDictionary.getSection('Global').getEntry(entryName).getValue)

      Donn

Leave a Reply


Your email address will not be published. Required fields are marked *