Main Content

Model

Reference another model to create model hierarchy

  • Model block

Libraries:
Simulink / Ports & Subsystems
HDL Coder / Ports & Subsystems

Description

The Model block references the specified model. It displays input and output ports that correspond to the top-level input and output ports of the referenced model. These ports allow you to connect the referenced model to other blocks in the parent model.

To determine whether the Model block is better suited for your goal than another block with similar functionality, see Explore Types of Model Components and Compare Capabilities of Model Components.

For instructions on how to reference a model with a Model block, see Reference Existing Models.

By default, the Model block displays a representation of the contents of the referenced model. For more information, see Preview Content of Model Components. To see the contents of a referenced model, double-click the Model block.

If you have a Simulink® Coder™ license, you can conceal the implementation details of a referenced model by protecting the model. To protect a model, see Protect Models to Conceal Contents (Simulink Coder). To reference a protected model, see Reference Protected Models from Third Parties.

Examples

expand all

You can include one model in another by using a Model block. Each Model block is a model reference, or a reference to another model. You can reference a model multiple times without making redundant copies, and multiple models can reference the same model.

Open the example, which contains a model named sldemo_mdlref_counter.

Before you reference a model, such as sldemo_mdlref_counter, consider its configuration, interface, and contents.

sldemo_mdlref_counter uses a fixed-step discrete solver and contains three Inport blocks and one Outport block.

  • The Inport block named upper provides the upper limit for the counter.

  • The Inport block named input provides the value that the counter increments at each time step.

  • The Inport block named lower provides the lower limit, or starting value, for the counter.

  • The Outport block named output provides the current count.

Each Inport block represents a model input, and each Outport block represents a model output.

In a new model, add a Model block.

In the Property Inspector, set Model name to sldemo_mdlref_counter.

To better display the information on the block icon, drag a corner of the Model block until no information overlaps.

The Model block icon displays:

  • The name of the referenced model: sldemo_mdlref_counter

  • Input ports named upper, input, and lower

  • An output port named output

Configure the top model for fixed-step discrete simulation.

  1. On the Modeling tab, click Model Settings.

  2. In the Configuration Parameters dialog box, in the Solver pane, set Type to Fixed-step and Solver to discrete (no continuous states).

Connect inputs and outputs to the Model block that match the expected inputs and outputs of the referenced model.

  • To represent the upper limit of the counter, add a Constant block with Constant value set to 100. Then, connect it to the upper port.

  • To represent the counter increment, add a Constant block with Constant value set to 1. Then, connect it to the input port.

  • To represent the lower limit of the counter, add a Constant block with Constant value set to 0. Then, connect it to the lower port.

  • To display the counter output in a plot, add a Scope block. Then, connect it to the output port.

In the toolstrip, click Run.

The top model simulates and executes the referenced model. The Scope window shows the output count for the simulation.

Ports

Input

expand all

The Model block has an input port for each input port of the model it references. The input ports of referenced models are defined by Inport and In Bus Element blocks. The name of the Model block port matches the name of the corresponding port in the referenced model. The input signal, message, or function call for each Model block port must be valid for the corresponding port in the referenced model. For more information, see Define Model Reference Interfaces.

Tips

  • Signal attributes in a referenced model are independent from the context of the Model block. For example, signal dimensions and data types do not propagate across the Model block boundary. To define signal attributes in a referenced model, define block parameters for root-level Inport and In Bus Element blocks.

  • Function calls connected to an input port pass into the referenced model. To conditionally execute the referenced model based on a function call, see Function Call.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | Boolean | fixed point | enumerated | bus | image
Complex Number Support: Yes

Output

expand all

The Model block has an output port for each output port of the model it references. The output ports of referenced models are defined by Outport and Out Bus Element blocks. The name of the port on the Model block matches the name of the corresponding port in the referenced model. The output signals and messages of a Model block are the signals and messages connected to the Outport and Out Bus Element blocks in the referenced model. See Define Model Reference Interfaces.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | Boolean | fixed point | enumerated | bus | image
Complex Number Support: Yes

Control

expand all

Conditional Execution

The enable port appears at the top of the Model block. The port label is an icon that represents an enable signal.

Enable port on Model block

The control signal that connects to the port determines when to execute the referenced model. For more information, see Conditionally Execute Referenced Models.

Dependencies

To enable this port, add an Enable block to the top level of the referenced model.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | Boolean | fixed point

The trigger port appears at the top of the Model block. The port label is an icon that represents a trigger signal.

Trigger port on Model block

The control signal that connects to the port determines when to execute the referenced model. For more information, see Conditionally Execute Referenced Models.

Dependencies

To enable this port, add a Trigger block to the top level of the referenced model and set its Trigger type to rising, falling, or either.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | Boolean | fixed point

The function-call port appears at the top of the Model block. The port label displays the name of the referenced model as a function.

Function-call port on Model block

The function-call control signal that connects to the port determines when to execute the referenced model. For more information, see Conditionally Execute Referenced Models.

Dependencies

To enable this port, add a Trigger block to the top level of the referenced model and set its Trigger type to function-call.

Model Events Simulation

The initialize event port provides a function-call control signal that triggers a model initialize event, which initializes the states of the referenced model.

The referenced model can contain an Initialize Function block that corresponds to the model initialize event. For more information, see Using Initialize, Reinitialize, Reset, and Terminate Functions.

Dependencies

To enable this port, select Show model initialize port.

A reset event port provides a function-call control signal that triggers a model reset event, which resets the states of the referenced model.

The referenced model must contain a Reset Function block that corresponds to each model reset event. For more information, see Using Initialize, Reinitialize, Reset, and Terminate Functions.

To specify the port name, use the Event name parameter of the Event Listener block in the Reset Function block.

Dependencies

To enable this type of port, select Show model reset ports.

A reinitialize event port provides a function-call control signal that triggers a model reinitialize event, which reinitializes the states of the referenced model.

The referenced model must contain a Reinitialize Function block that corresponds to each model reinitialize event. For more information, see Using Initialize, Reinitialize, Reset, and Terminate Functions.

To specify the port name, use the Event name parameter of the Event Listener block in the Reinitialize Function block.

Dependencies

To enable this type of port, select Show model reinitialize ports.

The terminate event port provides a function-call control signal that triggers a model terminate event, which reads and saves the states of the referenced model.

The referenced model can contain a Terminate Function block that corresponds to the model terminate event. For more information, see Using Initialize, Reinitialize, Reset, and Terminate Functions.

Dependencies

To enable this port, select Show model terminate port.

Periodic event ports provide function-call control signals that specify when to execute the model. For an example, see Test Rate-Based Model Simulation Using Function-Call Generators.

Each port label displays information about the periodic event, such as the sample time of the corresponding Inport block. For example, the Model block in this image displays periodic event ports and references a model with two discrete rates: 0.01 and 0.1.

A Model block has ports labeled D1[0.01] and D2[0.1].

Dependencies

To enable this type of port, set Schedule rates with to Ports.

Parameters

expand all

To interactively modify Model block parameters, select the Model block. Then, in the Simulink Toolstrip, on the Model Block tab, click Block Parameters.

Main

Specify fundamental information for the Model block.

Specify the file name of the referenced model. The file name must be a valid MATLAB® identifier for a model, as defined in Choose Valid Model File Names. The file extension is optional.

To select the model that you want to reference, click Browse. To view the specified model, click Open Model.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: ModelNameDialog
Values: '' (default) | filename in quotes
Data Types: char | string

Example: set_param(gcb,'ModelNameDialog','mymodel.slx')

To get the block parameter value programmatically, use the get_param function.

You can query the name of the referenced model in different formats:

  • ModelFile — Model name with file extension. When you do not specify a file extension, the first match that the software finds on the MATLAB path determines the file extension.

  • ModelNameDialog — Model name with or without file extension, depending on whether you specify a file extension.

  • ModelName — Model name without file extension. If you specify a model name with a file extension for ModelName, the software retains the file extension by setting ModelNameDialog and ModelFile.

Specify the simulation mode for the Model block. The simulation mode for the Model block can be different than the simulation mode of its referenced model and of other models in the model hierarchy.

  • Normal — Execute the referenced model interpretively, as if the referenced model is an atomic subsystem implemented directly within the parent model.

  • Accelerator — Create a MEX file for the referenced model. Then, execute the referenced model by running the S-function.

  • Software-in-the-loop (SIL) — This option requires an Embedded Coder® license. Generate production code based on the Code interface parameter setting. The code is compiled for and executed on the host platform.

  • Processor-in-the-loop (PIL) — This option requires an Embedded Coder license. Generate production code based on the Code Interface parameter setting. This code is compiled for and executed on the target platform. A target connectivity API implementation supports the exchange of data between the host and target at each time step during the PIL simulation.

The corners of the Model block indicate the simulation mode of the Model block. For normal mode, the corners have empty triangles. For accelerator mode, the corner triangles are filled in. For SIL and PIL modes, the corners are filled in and the word (SIL) or (PIL) appears on the block icon.

Although you can specify any simulation mode for a model, when you reference that model, the Model block specifies the simulation mode of the referenced model instance. The simulation mode of a parent model can override the simulation mode of a Model block.

For more information, see Choose Simulation Modes for Model Hierarchies.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: SimulationMode
Values: 'Normal' (default) | 'Accelerator' | 'Software-in-the-loop' | 'Processor-in-the-loop'

Example: set_param(gcb,'SimulationMode','Accelerator')

Specify whether to generate the code from the top model or the referenced model for SIL and PIL simulation modes. To deploy the generated code as part of a larger application that uses the referenced model, specify Model reference. To deploy the generated code as a standalone application, specify Top model.

  • Model reference — The code is generated from the referenced model as part of a model hierarchy. Code generation uses the slbuild('model', 'ModelReferenceCoderTarget') command.

  • Top model — The code is generated from the top model with the standalone code interface. Code generation uses the slbuild('model') command.

Dependencies

To enable this parameter, set Simulation mode to either Software-in-the-loop (SIL) or Processor-in-the-loop (PIL).

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: CodeInterface
Values: 'Model reference' (default) | 'Top model'

Example: set_param(gcb,'CodeInterface','Top model')

Model Events Simulation

Control when the referenced model executes and changes states.

Select this parameter to display the initialize event port. Clear this parameter to remove the port.

Dependencies

To enable this parameter, reference a model that is not configured for conditional execution.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: ShowModelInitializePort
Values: 'off' (default) | 'on'

Example: set_param(gcb,'ShowModelInitializePort','on')

Select this parameter to display the reinitialize event ports. Clear this parameter to remove the ports.

Dependencies

To enable this parameter, reference a model that is not configured for conditional execution and contains a Reinitialize Function block.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: ShowModelReinitializePorts
Values: 'off' (default) | 'on'

Example: set_param(gcb,'ShowModelReinitializePorts','on')

Select this parameter to display the reset event ports. Clear this parameter to remove the ports.

Dependencies

To enable this parameter, reference a model that is not configured for conditional execution and contains a Reset Function block.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: ShowModelResetPorts
Values: 'off' (default) | 'on'

Example: set_param(gcb,'ShowModelResetPorts','on')

Select this parameter to display the terminate event port. Clear this parameter to remove the port.

Dependencies

To enable this parameter, reference a model that is not configured for conditional execution. Then, select Show model initialize port.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: ShowModelTerminatePort
Values: 'off' (default) | 'on'

Example: set_param(gcb,'ShowModelTerminatePort','on')

Control the execution of the referenced model with periodic events.

Depending on the value of the Schedule rates with parameter, selecting this parameter will either display the periodic event ports on the Model block or create partitions to use with the Schedule Editor. When the Schedule rates with parameter is not visible, its default value (Ports) applies.

Clearing this parameter hides the periodic event ports and does not create partitions.

Dependencies

To enable this parameter, reference a model with discrete sample times that is not configured for conditional execution and is not an export-function model. When the parent model is rate based and the referenced model is an export-function model, Schedule rates is automatically selected.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: ScheduleRates
Values: 'off' (default) | 'on'

Example: set_param(gcb,'ScheduleRates','on')

Create ports or partitions.

  • Ports — Display periodic event ports for discrete rates in the referenced model.

    To manually specify port rates, use the set_param function to set the AutoFillPortDiscreteRates parameter of the Model block to 'off'. Then, specify the port rates with the PortDiscreteRates parameter.

  • Schedule Editor — Create partitions for the referenced model to use with the Schedule Editor.

Dependencies

To enable this parameter:

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: ScheduleRatesWith
Values: 'Ports' (default) | 'ScheduleEditor'

Example: set_param(gcb,'ScheduleRatesWith','ScheduleEditor')

Instance Parameters

Specify instance-specific values for model arguments.

Display instance parameters and specify instance-specific values. Instance parameters are block parameters that have been configured in the referenced model to use a different value for each instance of the model.

To specify instance-specific values, use the Value column in the table. To specify that a parameter value can be overridden by the parent model, select the Argument check box. For more information about configuring instance parameters in a referenced model and specifying instance-specific values at the Model block, see Parameterize Instances of a Reusable Referenced Model.

When changing instance-specific values, you can use a partial structure that has fields that correspond to only the instance parameters whose values you want to change. Instance parameters not included in the partial structure retain their values. In the structure, include the instance parameter names and values, specified as character vectors.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: ParameterArgumentValues
Values: structure with no fields (default) | structure
Data Types: struct
Parameter: InstanceParameters
Values: structure with fields Name, Value, Path, and Argument
Data Types: struct

Solver

Configure local solver parameters using a combination of the configuration parameters for the referenced model and the block parameters for each Model block that references the model.

Referenced Model Configuration Parameters

This parameter provides a hyperlink that opens the Configuration Parameters dialog box for the model referenced by the block. In the Configuration Parameters dialog box, select or clear the Use local solver when referencing model configuration parameter for the referenced model. When you select Use local solver when referencing model, the referenced model uses a local solver.

When you configure a referenced model to use a local solver, the local solver computes the state values for the referenced model during simulation. Using a local solver can improve simulation performance by allowing you to:

  • Specify a larger step size for a component with slower dynamics compared to the rest of the system.

  • Select a different solver that is more appropriate for the referenced model.

For more information, see Use Local Solvers in Referenced Models.

This parameter provides a hyperlink that opens the Configuration Parameters dialog box for the model referenced by the block. In the Configuration Parameters dialog box, select a value for the Solver parameter to specify the solver to use as the local solver for the referenced model.

The local solver must be a fixed-step solver.

Dependencies

To enable this parameter, select Use local solver when referencing model in the model configuration parameters for the model referenced by this block.

This parameter provides a hyperlink that opens the Configuration Parameters dialog box for the model referenced by the block. In the Configuration Parameters dialog box, specify the value for the Fixed-step size (fundamental sample time) parameter of the referenced model to specify the step size for the local solver.

The local solver step size must be an integer multiple of the parent solver step size.

Dependencies

To enable this parameter, select Use local solver when referencing model in the model configuration parameters for the model referenced by this block.

Model Block Parameters

Because the local solver execution is decoupled from the execution of the parent solver, the local solver extrapolates values from outside the model reference and provides interpolated values to the parent solver. For more information, see Use Local Solvers in Referenced Models.

Use this parameter to specify how the local solver extrapolates values from outside the model reference.

  • Auto — Use default input handling, which includes numerical compensation that improves data exchanges between the top and local solvers.

  • Zero-order hold — Use the last value calculated by the parent solver.

Specifying Auto input handling generally increases the accuracy of simulation results. The Auto input handling is more computationally intensive than the Zero-order hold input handling.

Consider using Zero-order hold input handling in any of these situations:

  • When simulation results are acceptable with Zero-order hold input handling and performance is a concern

  • When the referenced model does not have input ports

  • When input port values do not affect continuous state computations

  • When a significant part of the derivative is based on the state itself, for example, from feedback loops in the model

  • To improve local solver stability for a given step size

Dependencies

To enable this parameter, select Use local solver when referencing model in the model configuration parameters for the model referenced by this block.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: InputSignalHandling
Values: 'Auto' (default) | 'Zero-order hold'

Example: set_param(gcb,'InputSignalHandling','Zero-order hold')

Because the local solver execution is decoupled from the execution of the parent solver, the local solver extrapolates values from outside the model reference and provides interpolated values to the parent solver. For more information, see Use Local Solvers in Referenced Models.

Use this parameter to specify the interpolation method the local solver uses to provide values to the parent solver.

  • Use solver interpolant — Use the interpolant of the local solver to calculate the interpolated state and output signal values.

  • Zero-order hold — Use the last value calculated by the local solver before the current time for the top solver.

In general, using the solver interpolant for output handling increases accuracy. Zero-order hold output handling reduces computational complexity but also reduces accuracy.

Dependencies

To enable this parameter, select Use local solver when referencing model in the model configuration parameters for the model referenced by this block.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

Parameter: OutputSignalHandling
Values: 'Use solver interpolant' (default) | 'Zero-order Hold'

Example: set_param(gcb,'OutputSignalHandling','Zero-order Hold')

Block Characteristics

Data Types

Booleana | busa | doublea | enumerateda | fixed pointa | halfa | integera | singlea | stringa

Direct Feedthrough

no

Multidimensional Signals

yesa

Variable-Size Signals

yesa

Zero-Crossing Detection

no

a Actual data type or capability support depends on block implementation.

Tips

To programmatically determine whether a Model block references a protected model, use the get_param function to query the read-only ProtectedModel parameter of the Model block. If the referenced model is protected, the function returns 'on'. If the referenced model is unprotected, the function returns 'off'.

Extended Capabilities

Version History

Introduced before R2006a

expand all