Symbol Resolution

Symbols

When you create a Simulink^® model, you can use symbols to provide values and definitions for many types of entities in the model. Model entities that you can define with symbols include block parameters, configuration set parameters, data types, signals, signal properties, and bus architecture.

A symbol that provides a value or definition must be a legal MATLAB^® identifier. Such an identifier starts with an alphabetic character, followed by alphanumeric or underscore characters up to the length given by the function namelengthmax. You can use the function isvarname to determine whether a symbol is a legal MATLAB identifier.

A symbol provides a value or definition in a Simulink model by corresponding to some item that:

Exists in an accessible workspace
Has a name that matches the symbol
Provides the required information

Symbol Resolution Process

The process of finding an item that corresponds to a symbol is called symbol resolution or resolving the symbol. The matching item can provide the needed information directly, or it can itself be a symbol. A symbol must resolve to some other item that provides the information.

When the Simulink software compiles a model, it tries to resolve every symbol in the model, except symbols in MATLAB code that runs in a callback or as part of mask initialization. Depending on the particular case, the item to which a symbol resolves can be a variable, object, or function.

Simulink attempts to resolve a symbol by searching through the accessible workspaces in hierarchical order for a MATLAB variable or Simulink object whose name is the same as the symbol.

The search path is identical for every symbol. The search begins with the block that uses the symbol, or is the source of a signal that is named by the symbol, and proceeds upward. Except when simulation occurs via the sim command, the search order is:

Any mask workspaces, in order from the block upwards (see Masking Fundamentals).
The model workspace of the model that contains the block (see Model Workspaces).
The MATLAB base workspace (see Create and Edit Variables) or, if the model is linked to a data dictionary, the dictionary (see What Is a Data Dictionary?). If the data dictionary has the Enable dictionary access to base workspace property selected, the search treats the dictionary and the base workspace as a single namespace.

When simulation occurs via the sim command, the search order is:

Any mask workspaces, in order from the block upwards (see Masking Fundamentals).
Variables set by using the setVariable function on a Simulink.SimulationInput object with the Workspace argument specified.
The model workspace of the model that contains the block (see Model Workspaces).
Variables set by using the setVariable function on a Simulink.SimulationInput object.
The MATLAB base workspace (see Create and Edit Variables) or, if the model is linked to a data dictionary, the dictionary (see What Is a Data Dictionary?). If the data dictionary has the Enable dictionary access to base workspace property selected, the search treats the dictionary and the base workspace as a single namespace.

Note

If the model references a configuration set that is stored in the base workspace, the search begins in the base workspace. Unlike a configuration set that is attached to the model, a configuration set that is in the base workspace does not have access to the model workspace.

The Input and Initial state parameters do not load data from a data dictionary. When a model uses a data dictionary and you disable model access to the base workspace, the Input and Initial state parameters still access data in the base workspace.

If Simulink finds a matching item in the course of this search, the search terminates successfully at that point, and the symbol resolves to the matching item. The result is the same as if the value of that item had appeared literally instead of the symbol that resolved to the item. An object defined at a lower level shadows any object defined at a higher level.

If no matching item exists on the search path, Simulink attempts to evaluate the symbol as a function. If the function is defined and returns an appropriate value, the symbol resolves to whatever the function returned. Otherwise, the symbol remains unresolved, and an error occurs. Evaluation as a function occurs as the final step whenever a hierarchical search terminates without having found a matching workspace variable.

If the model that contains the symbol is a referenced model, and the search reaches the model workspace but does not succeed there, the search jumps directly to the base workspace or data dictionary without trying to resolve the symbol in the workspace of any parent model. Thus a given symbol resolves to the same item, irrespective of whether the model that contains the symbol is a referenced model. For information about model referencing, see Model References.

Numeric Values with Symbols

You can specify any block parameter that requires a numeric value by providing a literal value, a symbol, or an expression, which can contain symbols and literal values. Each symbol is resolved separately, as if none of the others existed. Different symbols in an expression can thus resolve to items on different workspaces, and to different types of item.

When a single symbol appears and resolves successfully, its value provides the value of the parameter. When an expression appears, and all symbols resolve successfully, the value of the expression provides the value of the parameter. If any symbol cannot be resolved, or resolves to a value of inappropriate type, an error occurs.

For example, suppose that the Gain parameter of a Gain block is given as cos(a*(b+2)). The symbol cos will resolve to the MATLAB cosine function, and a and b must resolve to numeric values, which can be obtained from the same or different types of items in the same or different workspaces. If the symbols resolve to numeric values, the value returned by the cosine function becomes the value of the Gain parameter.

Other Values with Symbols

Most symbols and expressions that use them provide numeric values, but the same techniques that provide numeric values can provide any type of value that is appropriate for its context.

Another common use of symbols is to name objects that provide definitions of some kind. For example, a signal name can resolve to a signal object (Simulink.Signal) that defines the properties of the signal, and a Bus Creator block Data type parameter can name a bus object (Simulink.Bus) that defines the properties of the bus. You can use symbols for many purposes, including:

Define data types
Specify input data sources
Specify logged data destinations

For hierarchical symbol resolution, all of these different uses of symbols, whether singly or in expressions, are the same. Each symbol is resolved, if possible, independently of any others, and the result becomes available where the symbol appeared. The only difference between one symbol and another is the specific item to which the symbol resolves and the use made of that item. The only requirement is that every symbol must resolve to something that can legally appear at the location of the symbol.

Limit Signal Resolution

Hierarchical symbol resolution traverses the complete search path by default. You can truncate the search path by using the Permit Hierarchical Resolution option of any subsystem. This option controls what happens if the search reaches that subsystem without resolving to a workspace variable. The Permit Hierarchical Resolution values are:

All
Continue searching up the workspace hierarchy trying to resolve the symbol. This is the default value.
None
Do not continue searching up the hierarchy.
ExplicitOnly
Continue searching up the hierarchy only if the symbol specifies a block parameter value, data store memory (where no block exists), or a signal or state that explicitly requires resolution. Do not continue searching for an implicit resolution. See Explicit and Implicit Symbol Resolution for more information.

If the search does not find a match in the workspace, and terminates because the value is ExplicitOnly or None, Simulink evaluates the symbol as a function. The search succeeds or fails depending on the result of the evaluation, as previously described.

Explicit and Implicit Symbol Resolution

Models and some types of model entities have associated parameters that can affect symbol resolution. For example, suppose that a model includes a signal named Amplitude, and that a Simulink.Signal object named Amplitude exists in an accessible workspace. If the Amplitude signal's Signal name must resolve to Simulink signal object option is selected, the signal resolves to the object. For more information, see Signal Properties.

If the option is not selected, the signal may or may not resolve to the object, depending on the value of Configuration Parameters > Diagnostics > Data Validity > Signal resolution. This parameter can suppress resolution to the object even though the object exists, or it can specify that resolution occurs on the basis of the name match alone. For more information, see Model Configuration Parameters: Data Validity > Signal resolution.

Resolution that occurs because an option such as Signal name must resolve to Simulink signal object requires it is called explicit symbol resolution. Resolution that occurs on the basis of name match alone, without an explicit specification, is called implicit symbol resolution.

Tip

Implicit symbol resolution can be useful for fast prototyping. However, when you are done prototyping, consider using explicit symbol resolution, because implicit resolution slows performance, complicates model validation, and can have nondeterministic effects.