Documentation

Partition Data for Model Reference Hierarchy Using Data Dictionaries

When you use model referencing to break a large system of models into smaller components and subcomponents, you can create data dictionaries to segregate the design data. Design data is the set of workspace variables that the models use to specify block parameters and signal characteristics. For basic information about data dictionaries, see What Is a Data Dictionary?.

You can migrate all of the models in a model reference hierarchy to use one or more data dictionaries using either of these techniques:

  • Migrate all of the models in the hierarchy at once to use a single dictionary. Then, create separate referenced dictionaries to organize the design data.

  • Incrementally migrate by beginning with the models at the bottom of the hierarchy. Use this technique if you cannot migrate all of the models at once.

Create a Dictionary for Each Component

This example shows how to partition design data into dictionaries. When you finish, each component and subcomponent in the system has a dictionary, and dictionary references allow the components and subcomponents to share data.

Explore Example Model Hierarchy

  1. Navigate to the folder matlabroot/help/toolbox/simulink/examples (open).

  2. Copy these files to a writable folder:

    • ProjectData.mat

    • ex_SystemModel

    • ex_PlantComp_Lvl1

    • ex_PlantComp_Lvl2

    • ex_ContrComp

    • ex_ContrComp_Sub1_Lvl1

    • ex_ContrComp_Sub1_Lvl2

    • ex_ContrComp_Sub2_Lvl1

    • ex_ContrComp_Sub2_Lvl2

  3. Load the MAT-file ProjectData.mat to create design data in the base workspace.

  4. Open the example model ex_SystemModel. This model is at the top of a reference hierarchy that includes the other example models.

  5. Select Analysis > Model Dependencies > Model Dependency Viewer > Models Only. The model reference hierarchy contains a system model, a plant component with two models, and a controller component. The controller component contains two subcomponents, each of which consist of two models.

  6. In the model, update the diagram. The signals in the model use the Simulink.Bus objects SensorBus and CtrlBus in the base workspace.

    The referenced models ex_PlantComp_Lvl1 and ex_ContrComp also use the bus objects. Therefore, the plant and controller components share the objects.

  7. In the MATLAB® base workspace, double-click the bus object SensorBus to view it in the Bus Editor. The data type of each signal element is set to FloatType, which is a Simulink.NumericType object in the base workspace.

    All of the models in the hierarchy use FloatType to control the data types of signals and parameters.

  8. In the Model Explorer Model Hierarchy pane, expand the node ex_SystemModel.

    The node Reference to SimConfigSet appears. SimConfigSet is a Simulink.ConfigSet object in the base workspace. All of the models in the hierarchy use references to SimConfigSet to maintain configuration parameter uniformity for simulation.

  9. Right-click the node Controller (ex_ContrComp) and select Open. In the Model Explorer Model Hierarchy pane, expand the new node ex_ContrComp.

    The nodes Reference to SimConfigSet and Reference to CodeGenConfigSet appear. CodeGenConfigSet is a Simulink.ConfigSet object in the base workspace. All of the models in the controller component use references to CodeGenConfigSet to maintain configuration parameter uniformity for code generation. The models in the plant component do not use CodeGenConfigSet.

  10. In the Model Hierarchy pane, select Base Workspace. In the Contents pane, right-click the variable diff and select Find Where Used. In the Select a system dialog box, select ex_SystemModel and click OK. If you see a message about updating the diagram, click OK.

    In the Contents pane, the variable diff is used by Constant blocks in the models ex_ContrComp_Sub1_Lvl1 and ex_ContrComp_Sub1_Lvl2, which make up the first controller subcomponent. Similarly, other models in the hierarchy share the base workspace variables coeff, init, and mu.

The table shows the models that share each variable in the base workspace.

Variable NameModels Using the VariableScope of Sharing
SimConfigSetAll models in the hierarchyShared globally by entire system
FloatTypeAll models in the hierarchyShared globally by entire system
CtrlBusAll models in the hierarchyShared globally by entire system
SensorBusAll models in the hierarchyShared globally by entire system
CodeGenConfigSetAll models in the controller componentShared by controller subcomponents
initex_ContrComp_Sub1_Lvl1 and ex_ContrComp_Sub2_Lvl1Shared by controller subcomponents
diffex_ContrComp_Sub1_Lvl1 and ex_ContrComp_Sub1_Lvl2Shared by models in the first controller subcomponent
coeffex_ContrComp_Sub2_Lvl1 and ex_ContrComp_Sub2_Lvl2Shared by models in the second controller subcomponent
muex_PlantComp_Lvl1 and ex_PlantComp_Lvl2Shared by models in plant component

Suppose that three teams of developers maintain the plant component and the two controller subcomponents. You can use data dictionaries to store and scope the shared design data.

Create System Dictionary

  1. In the model ex_SystemModel, select File > Model Properties > Link to Data Dictionary.

  2. In the dialog box, under Defined in, select Data Dictionary. Click New.

  3. Set the new dictionary name to System and click Save.

  4. In the Model Properties dialog box, click OK.

  5. Click Yes in response to the message about migrating workspace data.

  6. Click Yes in response to the message about removing imported items from the base workspace.

  7. Save the model.

You can simulate and generate code from the models in the hierarchy. All of the models in the hierarchy are linked to the dictionary. All of the variables in the base workspace now reside in the new dictionary System.sldd.

Create Dictionary for Plant Component

  1. Open the model ex_PlantComp_Lvl1.

  2. Select File > Model Properties > Link to Data Dictionary.

  3. In the dialog box, under Defined in, click New.

  4. Set the new dictionary name to Plant and click Save.

  5. In the Model Properties dialog box, click OK.

  6. In response to the message, click Move Data.

  7. Click Yes in response to the message about migrating data.

  8. Save the model.

The models in the plant component, ex_PlantComp_Lvl1 and ex_PlantComp_Lvl2, are linked to the new dictionary Plant.sldd. The other models in the hierarchy remain linked to System.sldd. Because the model ex_PlantComp_Lvl1 uses globally shared variables such as CtrlBus and FloatType, the migration process moves the variables to Plant.sldd. However, System.sldd references Plant.sldd, so all of the models in the hierarchy can continue to use the globally shared variables.

The variable that the plant models share, mu, also resides in Plant.sldd. Other variables such as init and diff remain in System.sldd.

The plant component can stand alone from the rest of the system because all of its data is in Plant.sldd. However, the controller component depends on the shared data that is also defined in Plant.sldd.

Create Dictionary for Controller Component

Open the model ex_ContrComp, which is the top model in the controller component. Link this model to a new dictionary named Contr.sldd. Then, save the model.

When you finish, the five models in the controller component are linked to Contr.sldd. Because the globally shared variables such as CtrlBus and FloatType still reside in the dictionary Plant.sldd, the dictionary Contr.sldd references Plant.sldd. Due to this reference, the models in the controller component can continue to use the globally shared variables.

The variables that the controller models share, such as diff, init, and CodeGenConfigSet, now reside in Contr.sldd.

Create Dictionary for First Controller Subcomponent

Open the model ex_ContrComp_Sub1_Lvl1. Link this model to a new dictionary named ContrSub1.sldd. Then, save the model.

When you finish, the models in the first controller subcomponent, ex_ContrComp_Sub1_Lvl1 and ex_ContrComp_Sub1_Lvl2, are linked to ContrSub1.sldd. The models in the second subcomponent remain linked to the dictionary Contr.sldd.

Create Dictionary for Second Controller Subcomponent

Open the model ex_ContrComp_Sub2_Lvl1. Link this model to a new dictionary named ContrSub2.sldd. Then, save the model.

The controller dictionary Contr.sldd references the subcomponent dictionaries, ContrSub1.sldd and ContrSub2.sldd. Therefore, the controller dictionary can use all of the data defined in the subcomponent dictionaries.

The first subcomponent dictionary, ContrSub1.sldd, defines data that the subcomponents share, such as CodeGenConfigSet. The second subcomponent dictionary, ContrSub2.sldd, references ContrSub1.sldd so that the second subcomponent can use this shared data.

The subcomponent dictionaries ContrSub1.sldd and ContrSub2.sldd reference Plant.sldd. Therefore, all of the models in the hierarchy can continue to use globally shared variables such as SensorBus and SimConfigSet, which are defined in Plant.sldd.

Inspect Data Storage

In the Model Explorer Model Hierarchy pane, select the dictionary node System. In the Contents pane, to view the contents of System.sldd, click the Show Current System and Below button . The contents of the Design Data and Configurations sections appear.

The DataSource column shows the variables that each dictionary stores.

All of the globally shared variables, such as FloatType and SimConfigSet, reside in Plant.sldd. The variable init, which both of the controller subcomponents share, resides in ContrSub1.sldd. Due to dictionary references created by the migration process, the models can still share these variables.

If the development teams assigned to the controller subcomponents must make changes to the globally shared variables, they must access the plant dictionary file. Similarly, if the team assigned to the second controller subcomponent must make changes to the variable init, they must access the first subcomponent dictionary file.

Optimize Data Sharing Using Reference Dictionaries

To share global variables such as SimConfigSet, FloatType, and SensorBus by clearly defining variable scope, you can create a reference dictionary. Add the new dictionary as a reference to all of the component and subcomponent dictionaries that require the shared data.

  1. Close all of the models that you have open.

    bdclose all

  2. In Model Explorer, select File > New > Data Dictionary.

  3. Set the new dictionary name to GlobalShare and click Save.

  4. In the Model Hierarchy pane, select the node ContrSub2. In the Dialog pane, click Add Reference.

  5. Double-click GlobalShare.sldd.

  6. In the Model Hierarchy pane, right-click the node ContrSub2 and select Save Changes.

  7. Add GlobalShare.sldd as a reference to the dictionaries ContrSub1.sldd and Plant.sldd. Save each dictionary after you add the reference.

  8. In the Model Hierarchy pane, select the node System.

  9. In the Contents pane, select the globally shared variables:

    • CtrlBus

    • SensorBus

    • SimConfigSet

    • FloatType

  10. In the DataSource column, select GlobalShare.sldd for any of the selected variables.

    All of the variables move from Plant.sldd to GlobalShare.sldd.

  11. Save changes to the dictionary System.sldd.

Now, if any of the three development teams need to make changes to the globally shared variables such as SimConfigSet and CtrlBus, they can access the dictionary GlobalShare.sldd. This dictionary contains only the variables that all of the models in the system share. Because the component and subcomponent dictionaries Plant.sldd, ContrSub1.sldd, and ContrSub2.sldd all reference the globally shared dictionary GlobalShare.sldd, all of the models in the hierarchy can use the data.

To further partition and scope the shared data, create another reference dictionary to contain the variables that the controller subcomponents share: init and CodeGenConfigSet.

  1. In Model Explorer, select File > New > Data Dictionary.

  2. Set the new dictionary name to ContrShare and click Save.

  3. In the Model Hierarchy pane, select the dictionary node ContrSub2. In the Dialog pane, select Add Reference.

  4. In the dialog box, double-click ContrShare.sldd.

  5. In the Model Hierarchy pane, right-click the node ContrSub2 and select Save Changes.

  6. Add ContrShare.sldd as a reference to ContrSub1.sldd and save the dictionary ContrSub1.sldd.

  7. Add GlobalShare.sldd as a reference to ContrShare.sldd and save the dictionary ContrShare.sldd.

  8. In the Model Hierarchy pane, select the node System.

  9. In the Contents pane, select these variables:

    • CodeGenConfigSet

    • init

  10. In the DataSource column, select ContrShare.sldd for any of the selected variables.

    All of the variables move from ContrSub2.sldd to ContrShare.sldd.

  11. Save changes to the dictionary System.sldd.

To further optimize the dictionary hierarchy, remove the unnecessary references that the migration process created. Also, remove the unnecessary references that you created from ContrSub1.sldd and ContrSub2.sldd to GlobalShare.sldd. Because ContrShare.sldd references GlobalShare.sldd, the controller subcomponent dictionaries can use the data in GlobalShare.sldd without referencing GlobalShare.sldd.

  1. In the Model Explorer Model Hierarchy pane, select the dictionary node ContrSub2. In the Dialog pane, in the Referenced Dictionaries list, select Plant and click Remove. Remove the references to GlobalShare.sldd and ContrSub1.sldd. Save the changes to ContrSub2.sldd.

  2. Remove the references to GlobalShare.sldd and Plant.sldd from ContrSub1.sldd. Save the changes to ContrSub1.sldd.

  3. Remove the reference to Plant.sldd from Contr.sldd. Save the changes to Contr.sldd.

Inspect Dictionary Hierarchy

To view the entire dictionary and model hierarchy, you can perform a dependency analysis in a Simulink® project.

  1. Open your saved model ex_SystemModel. Select File > Simulink Project > Create Project from Model.

  2. Specify a name for the project in the Project name box. Click Create.

  3. In the Simulink Project, click Dependency Analysis. Click Analyze.

The system model, ex_SystemModel, is linked to the dictionary System.sldd. The plant component, the controller component, and the controller subcomponents are each linked to a separate dictionary. These dictionaries form a reference hierarchy. To access the shared data, the component and subcomponent dictionaries reference the dictionaries ContrShare.sldd and GlobalShare.sldd.

To inspect the data in the dictionaries, use Model Explorer.

  1. In your saved model ex_SystemModel, click the data dictionary badge .

  2. In the Model Explorer Contents pane, click the column name DataSource to sort the design data. The dictionaries in the hierarchy partition the data based on the shared scope of each variable.

    You can also right-click the column name and select Group by This Column to group the entries by the dictionaries that define them.

  3. In the Model Hierarchy pane, under the node System, click the node Configurations. In the Contents pane, the Simulink.ConfigSet objects CodeGenConfigSet and SimConfigSet are stored in the shared dictionaries.

Strategies to Discover Shared Data

To learn how the models in a model reference hierarchy share data, use these techniques:

  • In an open model, select Edit > Find Referenced Variables. The Model Explorer displays the variables that the model uses, as well as the variables that referenced models use. You can then right-click a variable and select Find Where Used to display all of the models that use the variable. For more information, see Workspace Variables in Model Explorer.

  • At the command prompt, use the function Simulink.findVars to determine the variables a model uses. You can then use the function intersect to determine the variables two models, components, or subcomponents share.

Migrate Model Hierarchy to Dictionaries Incrementally

If you cannot migrate all of the models in a model reference hierarchy to a single dictionary at once, you can migrate an individual model, component, or subcomponent at the bottom of the hierarchy. Over time, you can migrate the entire hierarchy.

If you want to simulate and generate code from the hierarchy after you migrate each component, the components that you migrate cannot share any design data with other models in the hierarchy. In the example Create a Dictionary for Each Component, the components and subcomponents of a model reference hierarchy share data in the base workspace, such as Simulink.Bus and Simulink.Parameter objects. Due to these dependencies, if you migrate the hierarchy incrementally from the bottom, you cannot simulate or generate code from the hierarchy until you migrate all of the models.

Similarly, if you use configuration set references to maintain configuration parameter uniformity throughout the hierarchy, the component that you choose to migrate cannot share a configuration set with other models in the hierarchy. To permit simulation and code generation after you migrate the component, you must eliminate the dependency that the component has on the shared configuration set.

For example, when you migrate the component, copy the shared configuration set from the base workspace into the new dictionary. Then, rename the configuration set in the data dictionary, and set all of the models in the migrated component to use this renamed configuration set. The models in the migrated component use the configuration set in the data dictionary, while the rest of the models in the hierarchy use the configuration set in the base workspace. As you migrate additional components, set the models in each component to use the configuration set in the data dictionary.

If you choose to migrate a model reference hierarchy incrementally by using this technique, you must begin with the models or components at the bottom of the hierarchy. In the example Create a Dictionary for Each Component, a controller model references two subcomponents, each of which contains two models. You cannot migrate the controller model before you migrate the models in the controller subcomponents.

Explore Example Model Hierarchy

  1. Navigate to the folder matlabroot/help/toolbox/simulink/examples (open).

  2. Copy these files to a writable folder:

    • ProjectData_ind.mat

    • ex_SystemModel_ind

    • ex_Plant_L1_ind

    • ex_Plant_L2_ind

    • ex_Contr_L1_ind

    • ex_Contr_L2_ind

  3. Load the MAT-file ProjectData_ind.mat to create design data in the base workspace.

  4. Open the example model ex_SystemModel_ind. This model is at the top of a reference hierarchy that includes the other example models.

  5. Select Analysis > Model Dependencies > Model Dependency Viewer > Models Only. The model reference hierarchy contains a system model, a plant component with two models, and a controller component with two models.

  6. In the Model Explorer Model Hierarchy pane, select Base Workspace. In the Contents pane, right-click the variable diff and select Find Where Used. In the Select a system dialog box, select ex_SystemModel_ind and click OK. If you see a message about updating the diagram, click OK.

    In the Contents pane, the variable diff is used by Constant blocks in the models ex_Contr_L1_ind and ex_Contr_L2_ind, which make up the controller component. Similarly, other models in the hierarchy share the base workspace variable mu.

The table shows the models that share each workspace variable.

Variable NameModels Using the VariableScope of Sharing
diffex_ContrComp_Lvl1 and ex_ContrComp_Lvl2Shared by models in the controller component
muex_PlantComp_Lvl1 and ex_PlantComp_Lvl2Shared by models in plant component

Suppose that two teams of developers maintain the plant component and the controller component. You can use data dictionaries to store and scope the design data. The teams can incrementally migrate the components to use data dictionaries.

Create Data Dictionary for Controller Component

Suppose that only the controller component team is ready to migrate their models to a data dictionary. You can independently migrate these two models.

  1. Open the example model ex_Contr_L1_ind. This model is at the top of the controller component.

  2. Select File > Model Properties > Link to Data Dictionary.

  3. In the dialog box, under Defined in, select Data Dictionary and click New.

  4. Set the new dictionary name to Contr and click Save.

  5. In the Model Properties dialog box, click OK.

  6. Click Yes in response to the message about migrating workspace data.

  7. Click Yes in response to the message about removing imported items from the base workspace.

  8. Save the model.

You can simulate and generate code from the model hierarchy. The models in the controller component use the data in the dictionary Contr, which contains the variable diff. The other models in the hierarchy continue to use the data in the base workspace.

Create Data Dictionary for Plant Component

Open the example model ex_Plant_L1_ind. Link this model to a new data dictionary Plant.sldd. After you link the model to the new dictionary, save the model.

The migration process moves the variable mu into the new dictionary.

Create Data Dictionary for System Model

Open the example model ex_SystemModel_ind. Link this model to a new data dictionary System.sldd. After you link the model to the new dictionary, save the model.

The migration process causes the new dictionary, System.sldd, to reference the other dictionaries that you created.

Inspect Dictionary Hierarchy

Each of the components has a data dictionary. To view the entire dictionary and model hierarchy, you can perform a dependency analysis in a Simulink project.

  1. In your saved model ex_SystemModel_ind, select File > Simulink Project > Create Project from Model.

  2. Specify a name for the project in the Project name box. Click Create.

  3. In the Simulink Project, click Dependency Analysis. Click Analyze.

Each team's models are linked to the appropriate dictionaries. The system dictionary references the component dictionaries.

To inspect the data in the dictionaries, use the Model Explorer.

  1. In your saved model ex_SystemModel_ind, click the data dictionary badge .

  2. In the Model Explorer Contents pane, the data source for each entry is the dictionary for the appropriate component.

Related Examples

Was this topic helpful?