Model Configuration Command Line Interface

Overview

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.

Load and Activate a Configuration Set at the Command Line

To load a configuration set from a MATLAB® function or script:

  1. Use the getActiveConfigSet or getConfigSet function to get a handle to the configuration set that you want to update.

  2. Call the MATLAB function or execute the MATLAB script to load the saved configuration set.

  3. Optionally, use the attachConfigSet function to attach the configuration set to the model. To avoid configuration set naming conflicts, set allowRename to true.

  4. 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:

  1. Open the model.

  2. Use the Simulink.BlockDiagram.loadActiveConfigSet function to load the configuration set and make it active.

      Note:   If you load a configuration set with the same name as the:

      • Active configuration set, the software overwrites the active configuration set.

      • Inactive configuration set that is associated with the model, the software detaches the inactive configuration from the model.

Save a Configuration Set at the Command Line

To save an active or inactive configuration set as a MATLAB function or script:

  1. Use the getActiveConfigSet or getConfigSet function to get a handle to the configuration set.

  2. 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:

  1. Open the model.

  2. Use the Simulink.BlockDiagram.saveActiveConfigSet function to save the active configuration set.

Create a Freestanding Configuration Set at the Command Line

Copy a Configuration Set Stored in a Model

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.

Read 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, 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:

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

Create and Attach a Configuration Reference at the Command Line

To create and populate a configuration reference, Simulink.ConfigSetRef, 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(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.

Attach a Configuration Reference to Multiple Models at the Command Line

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')

Get 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')

Change Values in a Referenced Configuration Set

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:

  1. Follow the instructions in Obtain 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.

Obtain a Configuration Reference Handle

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.

Use refresh When 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 invalid. To avoid this situation, execute:

cref.refresh

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.

Was this topic helpful?