About Configuration References

A configuration reference in a model is a reference to a configuration set object in the base workspace or data dictionary. A model that has a configuration reference that points to a freestanding configuration set uses that configuration set when configuration reference is active. The model then has the same configuration parameters 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. For an example on how to use configuration references, see Share a Configuration for Multiple Models or Create and Attach a Configuration Reference.

Tip

Save or export the configuration set object. Otherwise, when you reopen your model, the configuration reference is unresolved. To set up your model to automatically load the configuration set object, see Callbacks for Customized Model Behavior.

Why Use Configuration References?

You can use configuration references and freestanding configuration sets to achieve these goals.

  • 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. Changing the value of any parameter in the set changes it for every model that uses the set. Use this feature to reconfigure many referenced models quickly and ensure consistent configuration of parent models and referenced models. If one model requires a different value for an individual parameter, you can override that parameter to change the value locally in the configuration reference. For more information, see Overriding Individual Configuration Parameters.

  • 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 referenced model that uses different configuration sets in different contexts contains a configuration reference that specifies the referenced model configuration set as a variable.

Unresolved Configuration References

When a configuration reference does not reference a valid configuration set, a warning indicates that the referenced configuration set cannot be found. If you activate an unresolved configuration reference, no warning or error appears. However, an unresolved configuration reference that is active provides no configuration parameter values to the model. Therefore, trying to build the model, simulate it, generate code for it, or otherwise require it to access configuration parameter values results in an error.

For more information, see Resolve a Configuration Reference.

Overriding Individual Configuration Parameters

When you reference the same configuration set from many models, there may be a model that requires a different value for an individual parameter. When you use a configuration reference, you can override an individual parameter to specify a setting that is different from the referenced configuration. The local setting affects only the configuration reference in which you override the parameter and does not affect the referenced configuration set or other configuration references.

If you have overridden a parameter, you can restore its value from the referenced configuration set. When you restore a parameter, it reflects the value in the referenced configuration and is no longer overridden. For more information, see Change Parameter Value in a Configuration Reference.

Configuration Reference Limitations

  • A configuration reference can link to another configuration reference, but you cannot nest a configuration reference beyond that depth.

  • 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 occurs, even if an active configuration reference points to that target. For more information about ActivateCallback functions, see rtwgensettings Structure (Simulink Coder).

  • Not all parameters in a reference can be overridden, for example, parameters that must be consistent in a model reference hierarchy.

Configuration References for Models with Older Simulation Target Settings

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

  • MATLAB Function

  • Chart

  • Truth Table

  • Attribute Function

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.

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 while a model is loading to ensure that simulation results are the same, no matter which version of the software that you use:

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

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

  • The new configuration set becomes active.

  • 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.

Related Examples

More About