Using Model Reference Variants

Adapting Models to Different Contexts

Many situations require the ability to customize a model to fit different contexts without having to replace the model entirely. For example, suppose a design engineer has a model that simulates a car on the road. Different versions of the car may have much in common yet differ in specific ways, such as using different fuels, having different size engines, or meeting different emission standards.

If each permutation required a separate model, the resulting combinatorial explosion could be unmanageable. Simulink therefore provides several techniques that you can use to customize a model to fit different contexts without needing to replace the model entirely. For example, you can:

• Change base workspace data values, as described in Tunable Parameters

• Select a subsystem from a library by using a Configurable Subsystem block.

• Use a mask to change a subsystem, as described in Creating Dynamic Masked Subsystems

• Change the arguments to a parameterized referenced model, as described in Parameterizing Model References

Where these techniques do not provide sufficient adaptability, you can configure any Model block to select the model that it references from a predefined set of models. The Model block selects the model to reference based on current values in the base workspace. This section describes the necessary Simulink techniques.

Back to Top

About Model Reference Variants

Model reference variants allow you to configure any Model block to select its referenced model from a set of candidate models. A model used as a model reference variant needs no special properties: functionally it is just another referenced model.

• Simulink selects the variant to use when you compile the model that contains the Model block.

• The selection depends on the values of one or more MATLAB variables and/or Simulink parameters in the base workspace.

To configure a Model block to select the model that it references, you:

• Provide a set of Boolean expressions that reference base workspace values.

• Associate each expression with one of the models that the block could reference.

The Boolean expressions must be organized so that one and only one expression is true for any combination of base workspace values. When you compile the model, Simulink evaluates all the expressions. Each Model block that uses model reference variants then selects the candidate model whose associated expression is true, and ignores all the other models. Compilation then proceeds just as if you had entered the name of the selected model literally in the Model block's Model name field.

When a candidate model is parameterized, as described in Parameterizing Model References, you can associate model argument values with the object whose Boolean expression selects the model. When that expression is true, the Model block provides the selected model with those argument values, just as it would if the values appeared literally in the Model blocks's Model argument values field. You can also specify whether the selected model executes in Accelerator, Normal, or PIL mode.

The Boolean expressions that control model reference variants reside in Simulink objects in the base workspace. Once you define such an object, you can reuse it with as many Model blocks as needed, so that all the Model blocks select the model that each references based on the same criteria. You can also use the same model as a variant more than once in a Model block, predicating each use on a different Boolean expression, and configuring the model differently for each use.

Reusing expressions and models allows you to globally reconfigure a model hierarchy to suit different environments by doing nothing more than changing base workspace values. No matter how many simulation environments you define, selecting an environment requires only setting variable or parameter values appropriately in the base workspace.

Most Simulink capabilities and tools work with variant models in the same way that they do with ordinary referenced models. The few exceptions are listed in Model Reference Variant Limitations. You can nest Model blocks that use variants to any level, provided that the resulting hierarchy satisfies all applicable requirements and limitations when you compile the model or generate code for it.

To see demos that show how to define model reference variants in Simulink and use them with enumerated types, access MATLAB Online Help and select:

• Simulink > Demos > Modeling Features > Model Reference > Model Reference Variants

• Simulink > Demos > Modeling Features > Model Reference > Model Reference Variants – Enumerations and Reuse

To see a demo that shows how to define model reference variants in Simulink and use them for simulation and code generation, access MATLAB Online Help and select either of the following:

• Real-Time Workshop > Demos > Variants > Code Variants Using Model Blocks

• Real-Time Workshop Embedded Coder > Demos > Variants > Code Variants Using Model Blocks

For complete information about generating code for variant referenced models, see Generating Code Variants for Variant Models. Reference information about the model reference variants API appears in the documention of the Model block and the Simulink.Variant class.

Back to Top

Model Reference Variant Components

To configure a model to use model reference variants, you must provide the following:

• Variant control variables — Base workspace variables or parameters that you set to specify the environment in which you want to simulate the model.

• Variant objects — Base workspace objects that contain Boolean expressions called variant conditions. Each variant object corresponds to a different simulation environment. See Simulink.Variant for reference information.

• Variant models — A set of candidate models that a particular Model block can reference. Each variant model has at least one associated variant object.

Before simulating, you set the variant control variables to values that describe the environment in which you want to simulate. When compiling the model, Simulink tests the variant condition specified by each variant object. The variant model whose variant object's condition is true becomes the active variant, which the Model block references during simulation. A Model block that uses model reference variants can be called a variant Model block.

Back to Top

Model Reference Variant Example

Suppose that an automobile can use either a diesel or a gasoline engine, and that the engine must meet either the European or American (USA) emission standard. Other parts of the automobile might also change to reflect the applicable fuel and emission standards, but they do not appear in this example.

Suppose that the Simulink model for the described automobile includes a Model block named Engine that uses model reference variants to select one of four referenced models, each representing one permutation of engine fuel and emission standards.

This section shows one way to specify the necessary variant control variables, variant objects, and variant models, and describes how those components work together. The next section, Implementing Model Reference Variants, shows you how to construct the example used in this section.

Opening the Example

To see the example, open the model Automobile.mdl by doing one of the following

• Click Automobile.mdl

• In the MATLAB command window, enter:

  cd([docroot '/toolbox/simulink/ug/examples/variants/mdlref']);
  Automobile

The example initially looks like this.

The icon on the lower left corner of the Model block indicates that the block uses model reference variants. The name at the top of the block is the name of the active variant. When you open the model, a callback function loads an M-file that populates the base workspace with the variables and objects that the model uses. The base workspace then contains these definitions:

Example Variant Control Variables

The example uses two variant control variables: FUEL and EMIS. The values used for the variables in the example, and the (arbitrarily assigned) meanings of those values, are:

The current variable values, as shown in the base workspace, specify that the fuel is diesel (FUEL==2), and the emission standard is American (EMIS==1). Techniques for defining variant control variables appear in Implementing Variant Control Variables.

Example Variant Objects

The example uses four variant objects, one for each of the four environments defined by the permutations of fuel and emission standards. The variant conditions and the objects that contain them are:

Because the fuel is diesel (2) and the emission standard is American (1) , the third variant condition, in the variant object DU, is true, and the rest are false. Techniques for defining variant control variables appear in Implementing Variant Objects.

Example Variant Models

The example contains a Model block named Engine that can reference one of four variant models, named GasolUSA, GasolEuro, DieselUSA, and DieselEuro. Each of the models is associated with a variant object as follows:

Because the variant condition associated with the variant object DU is true, the selected variant model is DieselUSA.mdl, which is correct for the specified fuel (diesel) and emission standard (American). The variant models themselves do not matter to this example, so each is a shell containing a callback that displays the model's name when it executes. The variant models are siblings of Automobile.mdl, so you can use the File > Open command to access and inspect them. Techniques for associating variant conditions with variant models appear in Enabling Model Variants and Specifying Variant Models.

Variant Components Relationship

This figure shows how the components of a variant model implementation work together to specify which variant a Model block will use for simulation. The figure uses the objects and values that appear in the example, which select DieselUSA.mdl as the active variant. The principles are the same for all model reference variants implementations.

Running the Example

Expose the MATLAB command window so you can see the messages it displays, then simulate the model Automobile. Because FUEL is 2 and EMIS is 1, the variant condition FUEL==2 && EMIS==1 is true, and the other three variant conditions are false. The true condition resides in the variant object DU, which is associated in the Model block with the model DieselUSA. The Model block therefore uses DieselUSA as its referenced model, and simulating Automobile runs a callback that displays:

Using variant model: DieselUSA.mdl

The top line in the Model block changes to display the name of the variant model that it used:

Now change EMIS to 2 in the base workspace and simulate the model again. The values FUEL==2 && EMIS==2 make the variant condition in DE evaluate to true, selecting the variant model DieselEuro.mdl. The simulation therefore displays Using variant model: DieselEuro.mdl. The top line in the Model block reads DieselEuro.

Back to Top

Model Reference Variant Requirements

A Model block that uses variant models, and every model used as a variant, must meet the following requirements:

• All variant models must exist on the MATLAB path (though not necessarily in the same directory).

• Variant control variables must be of a scalar noncomplex Boolean, integer, or enumerated data type.

You can enable or suppress warning messages about mismatches between a Model block and its referenced model by setting diagnostics on the Diagnostics Pane: Model Referencing.

Model reference variants must also satisfy the requirements listed in Simulink Model Referencing Requirements and the limitations listed in Simulink Model Referencing Limitations and Model Reference Variant Limitations. Additional requirements and limitations that apply to code generation only appear in Generating Code Variants for Variant Models.

Back to Top

Implementing Model Reference Variants

This section shows you how to use Simulink capabilities to implement model reference variants. See Model Reference Variant Requirements for a list of requirements that a Model block and all of its variant models must satisfy. The order of operations shown in this section is not required: any other order that provides the same specifications before model compilation occurs would do as well. The necessary steps, listed in the order described in this section, are:

• Implement variant control variables

• Implement variant objects

• Enable model variants

• Specify variant models

This section illustrates the described operations using the model Automobile.mdl shown in Model Reference Variant Example . You can read the section and apply the operations to your own model, or you can use the section as a tutorial, as follows:

1. Close Automobile.mdl if it is open, which automatically clears its variables and objects from the base workspace. Otherwise the leftover definitions would interfere with the operations described in this section.

2. Open the model ModRefVar.mdl by clicking ModRefVar.mdl or executing:

   run([docroot '/toolbox/simulink/ug/examples/variants/mdlref/ModRefVar.mdl'])

   The model initially looks like this:

   

3. Save the model in a writable working directory.

4. Follow the instructions in the rest of this section to implement the capabilities shown in Automobile.mdl.

You do not need to copy the four variant model files used in the example, because they are already on the MATLAB path and need no changes. The variant models are siblings of ModRefVar.mdl, so you can use the File > Open command to access and inspect them.

Implementing Variant Control Variables

A variant control variable used in simulation can be a MATLAB variable, or a Simulink.Parameter object that resides in the base workspace. A variant control variable used for code generation must be a Simulink parameter that meets the requirements described in Generating Code Variants for Variant Models. You can define control variables in the MATLAB Command Window or the Model Explorer. For example, to define the variables used in Automobile.mdl, do one of the following:

• Technique 1: In the MATLAB Command Window, enter (or paste from this page):

  EMIS = 1
  FUEL = 2

• Technique 2: In the Model Explorer, select the Base Workspace, then use Add MATLAB Variable to define each variant control variable.

Whichever technique you use, the base workspace should look like this when you are done:

Implementing Variant Objects

A variant control object is an instance of class Simulink.Variant that exists in the base workspace and specifies a variant condition. The object can have any unique legal name. A variant condition can include scalar variables, enumerated values, the operators ==, !=, &&, ||, and ~, and parentheses if needed for grouping.

You can define variant objects in the MATLAB Command Window or the Model Explorer. For example, to define the objects used in Automobile.mdl, do one of the following:

• Technique 1: In the MATLAB Command Window, enter (or paste from this page):

  GU=Simulink.Variant('FUEL==1 && EMIS==1')
  GE=Simulink.Variant('FUEL==1 && EMIS==2')
  DU=Simulink.Variant('FUEL==2 && EMIS==1')
  DE=Simulink.Variant('FUEL==2 && EMIS==2')

• Technique 2: In the Model Explorer:

  1. Select the Base Workspace.

  2. Choose Add > Simulink.Variant

     A new variant object named Variant appears in the base workspace.

  3. Use Contents (center) pane Name field to change the name of a variant object to GU.

  4. Use the Dialog (left) pane to enter the associated variant condition: FUEL==1 && EMIS==1. Do not surround the condition with parentheses or single quotes, which are required only by the MATLAB API.

  5. Repeat the instructions to define all needed variant objects and their variant conditions.

Whichever technique you use, the base workspace should look like this when you are done:

Enabling Model Variants

Defining variant control variables and objects does not enable model variants for any Model block. It only makes the resources available to every Model block that needs to use them. The Model block parameters dialog provides an optional section for enabling and specifying model reference variants. By default, model reference variants are disabled and the section for defining them is hidden. To enable variants and display the Model Reference Variants section:

1. Select the relevant Model block (Engine in the tutorial example).

2. Choose Model Reference Parameters from the Edit menu or the context menu.

   The Model block parameters dialog box opens. For a new block, model reference variants are initially disabled, and the dialog box looks like this:

   

3. Click Enable Variants at the bottom left of the dialog box to enable variants and display the Model Reference Variants section. For a new Model block, the dialog box now looks like this:

   

Once you enable variants, they remain enabled until you explicitly disable them. You can close and reopen the Model block as needed without affecting model variant enablement or specification. Whenever the Model Reference Variants section is open, you can use the Model Explorer button on the left side of the dialog to open the Model Explorer on the base workspace. See Changing Variant Model Definitions for information about the other buttons on the left side of the dialog.

Disabling Model Variants.   Disabling model reference variants hides the Model Reference Variants section, and leaves in effect the model name and execution environment of the variant that was active when variants were disabled. Subsequent changes to variant control variables, variant conditions, and other models other than the current model have no effect on the behavior of the Model block. To disable model variants:

• Click Disable variants at the bottom right of the Model block dialog box.

Disabling variants for one Model block has no effect on variants specified by any other Model block. Disabling variants does not discard any variant-related specifications; it just disables and hides them. If you later re-enable variants, the variant model specifications in the Model block will be the same as they were before, and the Model block will select a variant according to the current base workspace variables and conditions.

Specifying Variant Models

With variants enabled, the Model block displays the parameters specific to variant models, as well as the parameters that apply to any referenced model, as shown in the previous figure. A variant model specification in a Model block parameters dialog box must include at least:

• The name of a variant object, in the Variant object column of the Variant choices table.

• The name of a variant model, in the Model Name field of the Model parameters section.

• A simulation mode, in the Simulation mode field of the Model parameters section.

The variant objects and models do not need to exist at the time that you specify them in the Model block dialog box. Existing variant objects do not initially appear in the Variant object column, because Simulink cannot know in advance which existing objects are relevant to the particular Model block. You cannot use the Variant choices table to define variant objects: the objects must be defined separately, as described in Implementing Variant Objects. To specify the four variant models in the example:

1. Select the Model block named Engine, open its block parameters dialog, and enable variants as previously described.

2. In the Variant object column of the Variant choices table, double-click varObject. Edit its value to be the name of the variant object GU.

   For an existing variant object, Simulink retrieves the object's variant condition as soon as you click away from the Variant object field. Simulink displays the variant condition in the Condition field, but you cannot edit it there. To change a variant condition, you must redefine the variant object in the base workspace.

3. In the Model name field of the Model parameters section, enter the name of the associated variant model, GasolUSA.mdl, or browse to the model using the Browse button to the right of the Model name field. (You could also specify a protected model with a .mdlp extension. See Protecting Referenced Models.)

4. In the Simulation mode field of the Model parameters section, select Normal mode if you are building the Automobile model. (All simulation mode work with variant models. See Referenced Model Simulation Modes)

   For example, in ModRefVar.mdl the changed parts of the dialog box now look like this:

   

5. Click the Add a new variant button:

   A new Variant choices row appears below the first, for example:

   

6. Repeat the preceding instructions until you have specified all variant objects and their variant models. The complete specifications for ModRefVar.mdl (which you can paste from this page) are :

   Variant Object	Variant Model
   GU	GasolUSA.mdl
   GE	GasolEuro.mdl
   DU	DieselUSA.mdl
   DE	DieselEuro.mdl

   In ModRefVar.mdl the changed parts of the dialog box now look like this:

   

7. Click Apply or OK.

8. Connect the Model block to any input and output signals. (You could have done this at any time after the first variant model specification existed.) For example, the completed model ModRefVar.mdl looks like this:

   

Executing the Example

If you have used this section as a tutorial, you can now do anything with ModRefVar.mdl that you could do with Tutorial.mdl. See the following sections for more about what you can do with model reference variants. See the Model block documentation for information about all Model Block Parameters dialog box capabilities, including the capabilities of the Variant choices pane.

Back to Top

Saving Variant Referenced Models

Saving the model does not save the variant control variables or variant objects. As with all base workspace definitions, you must save the variables and objects in an M-file or MAT-file if you want to be able to reload them later. See the save command for more information.

Back to Top

Changing Variant Model Definitions

You can change variant control variables and variant objects between simulations as needed, using either the MATLAB Command Window or the Model Explorer. The changes take effect immediately. You can change variant model specifications between simulations by reopening the Model block parameters dialog, selecting any line in the Variant choices table, and modifying the specification. Use the four buttons at the left of the table to manipulate the table rows:

The order of rows in the table has no functional significance, but systematic ordering can help you to track the specifications. Changes to variant model specifications take effect when you click Apply or OK. You can change multiple specifications before saving the changes. Be sure to save the model to make the changes permanent, and to save any changed variables or objects using the save command.

Back to Top

Parameterizing Variant Models

You can parameterize any or all variant models, as described in Parameterizing Model References. You can parameterize some variants but not others, and you can parameterize different variants differently from one another. To parameterize a variant model, configure the model appropriately, then specify the necessary values in the Model parameters section's Model argument values field. The values needed by each variant model are the same as if it were an ordinary referenced model and no variants existed.

Back to Top

Reusing Variant Objects and Models

For simplicity the preceding example and instructions show only one Model block (Engine) and use each variant object and model only once. In a real model, more than one Model block might need to use model reference variants, and the various Model blocks might need to reuse some of the same variant objects and models.

For example, a real model of an automobile might include many other capabilities, like the fuel and exhaust systems, that need to change depending on the applicable fuel and emission standards. To model different contexts efficiently with variant referenced models, you can:

• Use the same variant object in more than one Model block, associating it with the same or a different model in each case, so that the blocks change their selected variants in synchrony as variant control values change. The separate uses of the variant object do not affect one another.

• Use the same variant model with more than one variant object in the same model block, assigning a different parameterization and/or execution mode in each case. The separate uses of the model do not affect one another.

You cannot use the same variant object more than once in the same Model block, because a conflict would occur if that variant condition were true. The same type of conflict occurs if two different variant objects used by a Model block have variant conditions that are true.

Back to Top

Overriding Variant Conditions

The bottom left of the Model block parameters dialog with variants enabled provides the Override variant conditions and use following variant checkbox. You can use this checkbox to override the boolean values of all variant conditions, and specify that a particular variant is the active variant. Initially the checkbox looks like this:

If you select the checkbox, the Variant field becomes active. You can then use its pulldown menu to select any available variant object. For example:

Cli ck Apply or OK after making the change. The variant object that you specified becomes the active variant, overriding all other specifications that determine which variant is active. The variant remains active until you either use the Variant pulldown to select another variant, or clear Override variant conditions and use following variant. The default variant model selection criteria then take effect. You can change the effect of the variant specified by the override by editing it in the same way you ordinarily would. See Changing Variant Model Definitions for details.

Back to Top

Variant Models and Enumerated Types

You can use enumerated types to give meaningful names to the integers that you use as values of variant control variables. See Using Enumerated Data for information about defining and using enumerated types. For example, suppose you define the following enumerated class, whose elements represent vehicle properties:

classdef(Enumeration) VP < Simulink.IntEnumType
  enumeration
    gasoline(1)
    diesel(2)
    American(1)
    European(2)
  end
end

This class could just as well have been two classes, one for fuels and one for emissions. If many more variant control variable values existed, the result might be more readable, but no computational difference would result.

With the class VP defined, you could use meaningful names to specify variant control variables and variant conditions. For example, you could use the techniques shown in Implementing Variant Control Variables and Implementing Variant Objects , substituting names for integers:

EMIS = American
FUEL = diesel

GU=Simulink.Variant('FUEL==VP.gasoline && EMIS==VP.American')
GE=Simulink.Variant('FUEL==VP.gasoline && EMIS==VP.European')
DU=Simulink.Variant('FUEL==VP.diesel && EMIS==VP.American')
DE=Simulink.Variant('FUEL==VP.diesel && EMIS==VP.European')

The ability to specify meaningful names rather than integers as the values of variant control variables facilitates creating complex variant model specifications. It also clarifies code generated from the model, because the code shows the names rather than arbitrary integers.

Back to Top

Generating Code for Variant Models

The bottom right of the Model block parameters dialog with variants enabled provides a Code Generation section that contains the Generate preprocessor conditionals checkbox:

This checkbox controls whether generated code contains preprocessor conditionals. The checkbox is relevant only to code generation, and has no effect on the behavior of a model in Simulink. The checkbox is available only for ERT targets when Inline parameters is 'on'. See Generating Code Variants for Variant Models for complete information.

Back to Top

Model Reference Variant Limitations

The following limitations apply to model reference variants.

• A model can perform only default data logging when used as a variant model.

• Model reference variants cannot be used with External mode.

In addition, a Model block and its variant models must satisfy all the requirements listed in Model Reference Variant Requirements.

Back to Top

Defining Function-Call Models

Protecting Referenced Models

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