Referencing Configuration Sets

Overview of Configuration References

By default, a configuration set resides within a single model, so that only that model can use it. Alternatively, you can store a configuration set independently, so that you can use it with any models. A configuration set that exists outside any model is a freestanding configuration set. Each model that uses a freestanding configuration set defines a configuration reference that points to the configuration set. The result is the same as if the referenced configuration set resides within the model.

Reasons to Use Configuration References

You can use configuration references and freestanding configuration sets to:

• Assign the same configuration set to any number of models

  Each model that uses a given configuration set contains a configuration reference that points to a MATLAB variable. The value of that variable is a freestanding configuration set. All the models share that configuration set, and changing the value of any parameter in the set changes it for every model that uses the set. Use this feature to reconfigure many submodels quickly and ensure consistent configuration of parent models and referenced models.

• Replace the configuration sets of any number of models without changing the model files

  When multiple models use configuration references to access a freestanding configuration set, assigning a different set to the MATLAB variable assigns that set to all models. Use this feature to maintain a library of configuration sets and assign them to any number of models in a single operation.

• Use different configuration sets for a referenced model used in different contexts without changing the model file

  A submodel that uses different configuration sets in different contexts contains a configuration reference that specifies the submodel configuration set as a variable. When you call an instance of the submodel, Simulink software assigns that variable a freestanding configuration set for the current context.

The next figure shows one way to use configuration references. Each model that appears in the Model Dependency Viewer specifies the configuration reference my_reference as its active configuration set, and my_reference points to the freestanding configuration set Configuration. The parameter values in Configuration therefore apply to all four models, and any parameter change in Configuration applies to all four models.

Basic Steps for Using a Configuration Reference

To use a configuration reference to link a freestanding configuration set to a model, follow these steps.

Comparison of Configuration References and Configuration Sets

A configuration reference is an object of type Simulink.ConfigSetRef, and a configuration set is an object of type Simulink.ConfigSet. The two classes are similar in many ways. Wherever the same operation is applicable to both, the relevant functions and methods overload to work with either class. For example, you can attach or activate a configuration set or a configuration reference using the same GUI operations and API syntax.

You cannot nest configuration references, because only one level of indirection is available. You can obtain configuration parameter values by operating on a configuration reference as if it were the configuration set that it references. See Getting Values from a Referenced Configuration Set for details. General information about configuration sets appears in Setting Up Configuration Sets.

Back to Top

Creating a Freestanding Configuration Set

All freestanding configuration sets reside in the base workspace as the values of MATLAB variables. Although you can store a configuration set in a model and point to it with a base workspace variable, such a configuration set is not freestanding. Trying to use it in a configuration reference causes an error. You can store a freestanding configuration set in the base workspace in these ways:

• Create and populate a new configuration set.

• Copy a configuration set that resides within a model.

• Load a configuration set from a MAT-file.

You can store any number of configuration sets in the base workspace by assigning each set to a different variable. Use any technique to manipulate a freestanding configuration set and its parameter values that you use with a configuration set stored directly in a model.

Creating and Populating a New Configuration Set

You can create a configuration set in the base workspace using any of the techniques described in Creating Configuration Sets or as follows:

cset = Simulink.ConfigSet

where cset is a new or existing base workspace variable. The new configuration set initially has default parameter values, copied from the default configuration set.

Copying a Configuration Set Stored in a Model

You can copy an existing configuration set to the base workspace using drag and drop operations described in Copying, Deleting, and Moving Configuration Sets, and assign the set to a MATLAB variable. For example:

cset = copy (getActiveConfigSet(mdl))
cset = copy (getConfigSet(mdl, ConfigSetName))

where mdl is any open model, and ConfigSetName is the name of any configuration set attached to the model. The first example obtains the currently active configuration set. The second example obtains a configuration set by specifying the name under which it appears in the Model Explorer.

Be sure to copy any configuration set obtained from an existing model, as shown in the examples. Otherwise, cset refers to the existing configuration set stored in the model, rather than a new freestanding configuration set in the base workspace. In this case, any use of a configuration reference that links to cset causes an error.

Reading a Configuration Set from a MAT-File

To use a freestanding configuration set across multiple MATLAB sessions, you can save it to a MAT-file. To create the MAT-file, you first copy the configuration set to a base workspace variable, as previously described, then save the variable to the MAT-file:

save (workfolder/ConfigSetName.mat, cset)

where workfolder is a working folder, ConfigSetName.mat is the MAT-file name, and cset is a base workspace variable whose value is the configuration set to save. When you later reopen your model, you can reload the configuration set into the variable:

load (workfolder/ConfigSetName.mat)

To execute code that reads configuration sets from MAT-files, use one of these techniques:

• The preload function of a top model

• The MATLAB startup script

• Interactive entry of load statements

Any technique that executes the necessary code works.

Back to Top

Creating and Attaching a Configuration Reference

After you store a configuration set in the base workspace, you can link to that set from a configuration reference and attach it to a model. The model then has the same configuration parameters that it does as if the referenced configuration set resides directly in the model. You can attach any number of configuration references to a model. Each reference must have a unique name.

GUI Techniques

To create a configuration reference using the GUI:

1. In the Model Explorer, select the model to which to attach the configuration reference.

2. Click the Add Reference tool or select Add > Configuration Reference.

   A new configuration reference attaches to the selected model. The default name of the new reference is Reference, with a digit appended if necessary to prevent name conflict. The name of the configuration reference appears in the Model Hierarchy pane under the Model Workspace icon, below the names of any configuration sets.

   

3. Select the new configuration reference in the Model Hierarchy pane, or right-click the configuration reference and select Open from the context menu.

   The Configuration Reference dialog box appears in the Dialog pane or a separate window.

   

4. Change the default Name if desired. This name exists for human readability and does not affect the configuration reference functionally.

5. Specify the Referenced configuration set to be the base workspace variable whose value is the freestanding configuration set that you want to reference.

   Tip   Do not specify the name of a configuration reference. If you nest a configuration reference, an error occurs.

6. Click OK or Apply.

   The Is Resolved field in the dialog box changes to yes.

   

If you do not specify a valid Referenced configuration, a warning appears. Using a configuration reference with an invalid Referenced configuration generates an error. The API equivalent of Referenced configuration is WSVarName. You can later use the GUI or API to correct the specification or provide a configuration set that has the correct name. See Unresolved Configuration References for more information.

API Techniques

To create and populate a configuration reference using the API:

1. Create the reference:

   cref = Simulink.ConfigSetRef

2. Change the default name if desired:

   cref.Name = 'ConfigSetRefName'

3. Specify the referenced configuration set:

   cref.WSVarName = 'cset'

   Tip   Do not specify the name of a configuration reference. If you nest a configuration reference, an error occurs.

4. Attach the reference to a model:

   attachConfigSet(mdl, cref, true)

   The third argument is optional and authorizes renaming to avoid a name conflict.

Using a configuration reference with an invalid WSVarName generates an error. The GUI equivalent of WSVarName is Referenced configuration. You can later use the API or GUI to correct the reference or provide a configuration set that has the correct name. See Unresolved Configuration References for more information.

Back to Top

Obtaining a Configuration Reference Handle

Most functions and methods that operate on a configuration reference take a handle to the reference. If you create a configuration reference programmatically, with a statement like

cref = Simulink.ConfigSetRef

the variable cref contains a handle to the reference. If you do not already have a handle, you can obtain one by executing:

cref = getConfigSet(mdl, 'ConfigSetRefName')

where ConfigSetRefName is the name of the configuration reference as it appears in the Model Explorer, for example, Reference. You specify this name by setting the Name field in the Configuration Reference dialog box or executing

cref.Name = 'ConfigSetRefName'

The technique for obtaining a configuration reference handle is the same you use to obtain a configuration set handle. Wherever the same operation applies to both configuration sets and configuration references, applicable functions and methods overloadto perform correctly with either class.

Back to Top

Attaching a Configuration Reference to Other Models

After you create a configuration reference and attach it to a model, you can attach copies of the reference to any other models. To create and attach a copy of a configuration reference, you can use any technique you use to copy and attach a configuration set. See Copying, Deleting, and Moving Configuration Sets and Configuration Set API.

Models do not share configuration reference objects. Each model has its own copy of any configuration reference attached to it, just as each has its own copy of any attached configuration set. Configuration references in different models establish configuration set sharing by specifying the same base workspace variable, which links different models to the same freestanding configuration set.

If you use the GUI, attaching an existing configuration reference to another model automatically attaches a copy, as distinct from a handle to the original. If necessary to prevent name conflict, the GUI adds or increments a digit at the end of the name of the copied reference. If you use the API, be sure to copy the configuration reference explicitly before attaching it, with statements like:

cref = copy (getConfigSet(mdl, ConfigSetRefName))
attachConfigSet (mdl, cref,  true)

If you omit the copy operation, cref becomes a handle to the original configuration reference, rather than a copy of the reference. Any attempt to use cref causes an error. If you omit the argument true to attachConfigSet, the operation fails if a name conflict exists.

The following example shows code for obtaining a freestanding configuration set and attaching references to it to two models. After the code executes, one of the models contains an internal configuration set and a configuration reference that points to a freestanding copy of that set. If the internal copy is extra, you can remove it with detachConfigSet, as shown in the last line of the example.

% Get copy of original config set as 
% a variable in the base workspace
open_system('mdl1')
% Get handle to local cset
cset = getConfigSet('mdl1', 'Configuration')
% Create freestanding copy; original remains in model
cset1 = copy(cset)
% In the original model, create a configuration 
% reference to the cset copy
cref1 = Simulink.ConfigSetRef
cref1.WSVarName = 'cset1'
% Rename if name conflict occurs
attachConfigSet('mdl1', cref1, true)

% In a second model, create a configuration 
% reference to the same cset 
open_system('mdl2')
% Rename if name conflict occurs
attachConfigSetCopy('mdl2', cref1, true)
% Delete original cset from first model
detachConfigSet('mdl1', 'Configuration')

Back to Top

Changing a Configuration Reference

You can change an existing configuration reference by reopening its Configuration Reference dialog box and changing the Name or Referenced configuration. Similarly, you can use the API on an existing configuration reference to change the Name or WSVarName. If you refer to a configuration set that does not yet exist, no error occurs, but the configuration reference is unusable. The configuration reference becomes usable as soon as the configuration set exists.

Back to Top

Activating a Configuration Reference

After you create a configuration reference and attach it to a model, activate it using any technique that activates a configuration set in the model:

• From the GUI, select Activate from the context menu of the configuration reference.

• From the API, execute setActiveConfigSet, specifying the configuration reference as the second argument.

When a configuration reference is active, the Is Active field of the Configuration Reference dialog box is yes. Also, the Model Explorer shows the name of the reference with the suffix (Active).

The freestanding configuration set of the active reference now provides the configuration parameters for the model that contains the reference.

Back to Top

Unresolved Configuration References

When a configuration reference does not specify a valid configuration set, the Is Resolved field of the Configuration Reference dialog box has the value no. If you activate an unresolved configuration reference, no warning or error occurs. However, an unresolved configuration reference that is Active provides no configuration parameter values to the model. Therefore:

• Fields that display values known only by accessing a configuration parameter, like Stop Time in the model window, are blank.

• Trying to build the model, simulate it, generate code for it, or otherwise require it to access configuration parameter values, causes an error.

Creating and Attaching a Configuration Reference describes techniques for resolving configuration references.

Back to Top

Getting Values from a Referenced Configuration Set

You can use get_param on a configuration reference to obtain parameter values from the linked configuration set, as if the reference object were the configuration set itself. Simulink software retrieves the referenced configuration set and performs the indicated get_param on it.

For example, if configuration reference cref links to configuration set cset, the following operations give identical results:

get_param (cset, 'StopTime')
get_param (cref, 'StopTime')

Back to Top

Changing Values in a Referenced Configuration Set

You cannot change a configuration set in any way, such as changing configuration parameter values, by operating on a configuration reference. With cref and cset as before, if you execute:

set_param (cset, 'StopTime', '300')
set_param (cref, 'StopTime', '300')          % ILLEGAL

the first operation succeeds, but the second causes an error. Instead, you must obtain the configuration set itself and change it directly, using the GUI or the API.

GUI Techniques

To obtain a referenced configuration set using the GUI:

1. Select the configuration reference in the Model Hierarchy pane, or right-click the configuration reference and select Open from the context menu.

   The Configuration Reference dialog box appears in the Dialog pane or a separate window.

   

2. Click Open to the right of the Referenced configuration field.

   The Configuration Parameters dialog box opens on the configuration set specified by Referenced configuration. You can now change and apply or save parameter values as you would for any configuration set.

API Techniques

To obtain a referenced configuration set using the API:

1. Obtain a handle to the configuration reference, as described in Obtaining a Configuration Reference Handle.

2. Obtain the configuration set cset from the configuration reference cref:

   cset = cref.getRefConfigSet

   You can now use set_param on cset to change parameter values. For example:

   set_param (cset, 'StopTime', '300')

   Tip   If you want to change parameter values through the GUI, execute: cset.openDialog The Configuration Parameters dialog box opens on the specified configuration set.

Back to Top

Replacing a Referenced Configuration Set

You can replace the base workspace variable and configuration set that a configuration reference uses. However, the pointer from the configuration reference to the configuration set becomes stale. To avoid this situation, execute:

cref.refresh

where cref is the configuration reference. If you do not execute refresh, the configuration reference continues to use the previous instance of the base workspace variable and its configuration set. This example illustrates the problem.

% Create a new configuration set
cset1 = Simulink.ConfigSet;
% Set a non-default stop time
set_param (cset1, 'StopTime', '500')
% Create a new config reference
cref1 = Simulink.ConfigSetRef;
% Resolve the config ref to the set
cref1.WsVarName = 'cset1';
% Attach the config ref to an untitled model
attachConfigSet('untitled', cref1, true)
% Set the active configuration set to the reference
setActiveConfigSet('untitled','Reference')
% Replace config set in the base workspace
cset1 = Simulink.ConfigSet;
% Call to refresh is commented out!
% cref1.refresh;
% Set a different stop time
set_param (cset1, 'StopTime', '75')

If you simulate the model, the simulation stops at 500, not 75. Calling cref1.refresh as shown prevents the problem.

Back to Top

Building Models and Generating Code

The Real-Time Workshop pane of the Configuration Parameters dialog box contains a Build button. Its availability depends on whether the configuration set displayed by the dialog box resides in a model or is a freestanding configuration set.

• When the pane displays a configuration set stored in a model, the Build button is available. You can use it to generate and compile code for the model.

• When the pane displays a freestanding configuration set, the Build button is unavailable. The configuration set does not know which (if any) models link to it.

To provide the same capabilities whether a configuration set resides in a model or is freestanding, the Configuration Reference dialog box contains a Build button. This button has the same effect as its equivalent in the Configuration Parameters dialog box and operates on the model that contains the configuration reference.

Back to Top

Configuration Reference Limitations

• You cannot nest configuration references. Only one level of indirection is available, so a configuration reference cannot link to another configuration reference. Each reference must specify a freestanding configuration set.

• If you replace the base workspace variable and configuration set that configuration references use, execute refresh for each reference that uses the replaced variable and set. See Replacing a Referenced Configuration Set.

• If you activate a configuration reference when using a custom target, the ActivateCallback function does not trigger to notify the corresponding freestanding configuration set. Likewise, if a freestanding configuration set switches from one target to another, the ActivateCallback function does not trigger to notify the new target. This behavior applies, even if an active configuration reference points to that target. For more information about ActivateCallback functions, see rtwgensettings Structure in the Real-Time Workshop Embedded Coder Developing Embedded Targets documentation.

Back to Top

Configuration References for Models with Older Simulation Target Settings

Suppose that you have a nonlibrary model that contains one of these blocks:

• Embedded MATLAB Function block

• Stateflow chart

• Truth Table block

• Attribute Function block

In R2008a and earlier, this type of nonlibrary model does not store simulation target (or sfun) settings in the configuration parameters. Instead, the model stores the settings outside any configuration set.

When you load this older type of model, the simulation target settings migrate to parameters in the active configuration set.

• If the active configuration set resides internally with the model, the migration happens automatically.

• If the model uses an active configuration reference to point to a configuration set in the base workspace, the migration process is different.

The following sections describe the two types of migration for nonlibrary models that use an active configuration reference.

Default Migration Process That Disables the Configuration Reference

Because multiple models can share a configuration set in the base workspace, loading a nonlibrary model cannot automatically change any parameter values in that configuration set. By default, these actions occur during loading of a model to ensure that simulation results are the same, no matter which version you use:

1. A copy of the configuration set in the base workspace attaches to the model.

2. The simulation target settings migrate to the corresponding parameters in this new configuration set.

3. The new configuration set becomes active.

4. The old configuration reference becomes inactive.

A warning message appears in the MATLAB Command Window to describe those actions. Although this process ensures consistent simulation results for the model, it disables the configuration reference that links to the configuration set in the base workspace.

Optional Migration Process That Restores the Configuration Reference

If you want your models to retain an active configuration reference, use the updatecsref utility. This utility can compare the simulation target settings among all specified nonlibrary models with the parameters of the configuration set in the base workspace.

• If all settings are consistent with parameters in the shared configuration set, the utility does not perform any updates on the shared set.

• If all settings are not consistent, the utility provides a list of differences in the Command Window.

  The utility copies simulation target settings to the shared configuration set only if you approve the changes.

Suppose that you have models created in R2008a that contain:

• Stateflow charts

• Identical, non-default simulation target settings

• Active configuration references that point to the same configuration set in the base workspace

To run the updatecsref utility on these models, follow these steps:

1. At the command prompt, type:

   updatecsref('modelfile1', 'modelfile2', ..., 'modelfileN')

2. For each model, the utility looks for the active configuration reference that points to a configuration set in the base workspace. Sample messages include:

   Analyzing 'active_csref_8a_v1'
   Found the following valid configuration reference(s) in model 'active_csref_8a_v1'
   [1] Configuration reference 'Ref' points to the base workspace configuration set
   object 'cset'
   It will be used as the active configuration set.  Do you want to continue? (Y/n)
   
   Analyzing 'active_csref_8a_v2'
   Found the following valid configuration reference(s) in model 'active_csref_8a_v2'
   [1] Configuration reference 'Ref' points to the base workspace configuration set
   object 'cset'
   It will be used as the active configuration set.  Do you want to continue? (Y/n)

   If you approve this shared configuration set, choose Y. Otherwise, choose n to stop the migration process.

3. All differences between the simulation target settings and the shared configuration set appear. Sample messages include:

   Parameter 'SFSimEcho' of 'cset' will be changed from 'on' to 'off'
   Parameter 'SFSimOverflowDetection' of 'cset' will be changed from 'on' to 'off'
   Do you want to proceed and change base workspace object 'cset'? (Y/n)

   If you agree with all changes to the configuration set in the base workspace, choose Y. Otherwise, choose n to stop the migration process.

   Note   If any simulation target settings between nonlibrary models are inconsistent, these messages appear in the Command Window: A list of the differences A request to update your models to ensure consistent settings In this case, the utility exits automatically. After you update your models as requested, you can start over from step 1.

4. The utility displays messages about updates to your nonlibrary models and the shared configuration set.

   Your models continue to use an active configuration reference to point to the configuration set in the base workspace.

Note   For more information about using the updatecsref utility, type help updatecsref at the command prompt.

Back to Top

Setting Up Configuration Sets

Running Simulations

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit