|On this page…|
An application programming interface (API) lets you create and manipulate configuration sets at the command line or in a script. The API includes the Simulink.ConfigSet and Simulink.ConfigSetRef classes and the following functions:
These functions, along with the methods and properties of Simulink.ConfigSet class, allow you to create a script to:
Create and modify configuration sets.
Attach configuration sets to a model.
Set the active configuration set for a model.
Open and close configuration sets.
Detach configuration sets from a model.
Save configuration sets.
Load configuration sets.
For examples using the preceding functions and the Simulink.ConfigSet class, see the function and class reference pages.
To load a configuration set from a MATLAB® function or script:
Call the MATLAB function or execute the MATLAB script to load the saved configuration set.
Optionally, use the attachConfigSet function to attach the configuration set to the model. To avoid configuration set naming conflicts, set allowRename to true.
Optionally, use the setActiveConfigSet function to activate the configuration set.
Alternatively, to load a configuration set at the command line and make it the active configuration set:
Open the model.
Use the Simulink.BlockDiagram.loadActiveConfigSet function to load the configuration set and make it active.
To save an active or inactive configuration set as a MATLAB function or script:
Use the saveAs method of the Simulink.Configset class to save the configuration set as a function or script.
Alternatively, to save the active configuration set:
Open the model.
Use the Simulink.BlockDiagram.saveActiveConfigSet function to save the active configuration set.
Create a freestanding configuration set to be referenced by a configuration reference in several models. You must copy any configuration set obtained from an existing model, otherwise, cset refers to the existing configuration set stored in the model, rather than a new freestanding configuration set in the base workspace. For example, use one of the following:
cset = copy (getActiveConfigSet(model))
cset = copy (getConfigSet(model, ConfigSetName))
model is any open model, and ConfigSetName is the name of any configuration set attached to the model.
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, then save the variable to the MAT-file:
save (workfolder/ConfigSetName.mat, cset)
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:
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
To create and populate a configuration reference, Simulink.ConfigSetRef, using the API:
Create the reference:
cref = Simulink.ConfigSetRef
Change the default name if desired:
cref.Name = 'ConfigSetRefName'
Specify the referenced configuration set:
cref.WSVarName = 'cset'
Attach the reference to a model:
attachConfigSet(model, cref, true)
The third argument is optional and authorizes renaming to avoid a name conflict.
Using a configuration reference with an invalid configuration set, WSVarName, generates an error and is called an unresolved configuration reference. The GUI equivalent of WSVarName is Referenced configuration. You can later use the API or GUI to provide the name of a freestanding configuration set. For more information, see Unresolved Configuration References.
After you create a configuration reference and attach it to a model, you can attach copies of the reference to any other models. Each model has its own copy of any configuration reference attached to it, just as each model has its own copy of any attached configuration set.
If you use the GUI, attaching an existing configuration reference to another model automatically attaches a distinct copy to the model. 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(model, ConfigSetRefName)) attachConfigSet (model, 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 from 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 an extra copy, you can remove it with detachConfigSet, as shown in the last line of the example.
open_system('model1') % Get handle to local cset cset = getConfigSet('model1', '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' % Attach the configuration reference to the model attachConfigSet('model1', cref1, true) % In a second model, create a configuration % reference to the same cset open_system('model2') % Rename if name conflict occurs attachConfigSetCopy('model2', cref1, true) % Delete original cset from first model detachConfigSet('model1', 'Configuration')
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')
By operating on only a configuration reference, you cannot change the referenced configuration set parameter values. 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.
To obtain a referenced configuration set using the API:
Follow the instructions in Obtain a Configuration Reference Handle.
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')
Most functions and methods that operate on a configuration reference take a handle to the reference. When you create a configuration reference:
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(model, 'ConfigSetRefName')
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 technique you use to obtain a configuration set handle. Wherever the same operation applies to both configuration sets and configuration references, applicable functions and methods overload to perform correctly with either class.
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 invalid. To avoid this situation, execute:
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 configuration reference cref1 = Simulink.ConfigSetRef; % Resolve the configuration reference to the configuration set cref1.WsVarName = 'cset1'; % Attach the configuration reference 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.