Main Content

Model

Reference another model to create model hierarchy

expand all in page
  • 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

Open Model

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, on the Solver pane, set Type to Fixed-step and Solver to discrete (no continuous states).

  3. Click OK.

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.

Open Live Script

Open the model SecondOrderSystemTop. The model contains a Ramp block that provides the input signal for a Model block that references a model of a second-order system. The Model block output signal connects to an Outport block.

topmdl = "SecondOrderSystemTop";
open_system(topmdl)

The model SecondOrderSystemTop.

To navigate inside the referenced model, double-click the Model block. Alternatively, create a Simulink.BlockPath object for the Model block and use the open function to open the referenced model in the context of the model hierarchy.

mdlblkpath = Simulink.BlockPath(topmdl + "/Model");
open(mdlblkpath)

The contents of the model reference.

The referenced model implements the second-order system using a Transfer Fcn block and contains a Step block that models a change or disturbance to the system.

The system transfer function is specified in the Transfer Fcn block using two model workspace variables, wn and z, which represent the natural frequency of the system, in radians per second, and the system damping coefficient.

Configure the system with a natural frequency of 100 radians per second by specifying the value of the variable wn as 100 in the model workspace.

refmdl = "SecondOrderSystem";
mdlwksp = get_param(refmdl,"ModelWorkspace");
assignin(mdlwksp,"wn",100)

Configure the referenced model to use a local solver with a step size of 0.01 seconds. You can configure the settings for the referenced model from the top model using the Property Inspector or the Block Parameters dialog box.

  1. Open the Property Inspector. On the Modeling tab, expand the Design section and select Property Inspector, or press Ctrl+Shift+I.

  2. To open the Configuration Parameters dialog box for the referenced model, select the Model block. Then, in the Property Inspector, expand the Solver section and click the hyperlink next to the Use local solver parameter.

  3. Configure the model to use a local solver when referenced in a model hierarchy. In the Configuration Parameters dialog box, on the Model Referencing pane, select Use local solver when referencing model.

  4. Select the fixed-step ode3 as the local solver. On the Solver pane, from the Type list, select Fixed-step. Then, from the Solver list, select ode3 (Bogacki-Shampine).

  5. Set the local solver step size to 0.01 seconds. On the Solver pane, expand Solver details. Then, in the Fixed-step size (fundamental sample time) box, enter 0.01.

  6. Click OK.

Alternatively, use the set_param function to configure the parameters.

set_param(refmdl,UseModelRefSolver="on",...
    SolverType="Fixed-Step",Solver="ode3",FixedStep="0.01")

In the top model, the Model block indicates the local solver you specify.

The solver name ode3 is on the bottom of the Model block icon.

Specify the communication step size for the model reference. The communication step size specifies when the parent and local solvers exchange data and is registered as a discrete sample time in the top model.

The Ramp block in the top model has a slope of 0.2, and the top solver uses a step size of 0.2 seconds. Because the input signal from the top model changes slowly compared to the dynamics of the second-order system, the communication step size can be much larger than the local solver step size without significant effect on the accuracy of the simulation results.

Specify the communication step size as 0.4 seconds. Select the Model block. Then, in the Property Inspector, under Solver, in the Communication step size box, enter 0.4.

Alternatively, use the set_param function to set the CommunicationStepSize parameter.

set_param(topmdl + "/Model",CommunicationStepSize="0.4")

Simulate the model, using the local solver to compute the response of the second-order system.

out = sim(topmdl);

To view the simulation results, open the Simulation Data Inspector. On the Simulation tab, under Review Results, click Data Inspector. Alternatively, call the Simulink.sdi.view function.

Simulink.sdi.view

Plot the signals named System Response and System Response - Top on separate subplots. Alternatively, use the Simulink.sdi.loadView function to load the view named FastSecondOrderSystem, which was created for this example.

Simulink.sdi.loadView("FastSecondOrderSystem.mldatx");

Two subplots in the Simulation Data Inspector display the system response. The top plot shows the system response logged inside the referenced model, and the bottom plot shows the system response logged from the top model.

The System Response and System Response - Top signals are the same signal, logged in different locations. The System Response signal is logged inside the referenced model at a rate determined by the local solver step size. The System Response - Top signal is logged by the Outport block in the top model at a rate determined by the top solver step size. Because the local solver step size is much smaller than the top solver step size, the System Response signal captures the system response to the change in the input signal when the Step block output value changes with higher fidelity.

In the System Response signal, you can see the effect of the local solver interpolating the input signal with a zero-order hold between each communication step. If you zoom on the time axis around 5 seconds, you can see the oscillations in the system response to the step.

A subplot in the Simulation Data Inspector shows the signal named System Response between simulation times of approximately 3 seconds and 7 seconds.

Open Live Script

Open the model SecondOrderSystemTop. The model contains a Ramp block that provides the input signal for a Model block that references a model of a second-order system. The Model block output signal connects to an Outport block.

topmdl = "SecondOrderSystemTop";
open_system(topmdl)

The model SecondOrderSystemTop.

To navigate inside the referenced model, double-click the Model block. Alternatively, create a Simulink.BlockPath object for the Model block and use the open function to open the referenced model in the context of the model hierarchy.

mdlblkpath = Simulink.BlockPath(topmdl + "/Model");
open(mdlblkpath)

The contents of the model reference.

The referenced model implements the second-order system using a Transfer Fcn block and contains a Step block that models a change or disturbance to the system.

The system transfer function is specified in the Transfer Fcn block using two model workspace variables, wn and z, which represent the natural frequency of the system, in radians per second, and the system damping coefficient.

Configure the system with a natural frequency of 1 radian per second by specifying the value of the variable wn as 1 in the model workspace.

refmdl = "SecondOrderSystem";
mdlwksp = get_param(refmdl,"ModelWorkspace");
assignin(mdlwksp,"wn",1)

Configure the referenced model to use a local solver with a step size of 0.4 seconds. You can configure the settings for the referenced model from the top model using the Property Inspector or the Block Parameters dialog box.

  1. Open the Property Inspector. On the Modeling tab, expand the Design section and select Property Inspector, or press Ctrl+Shift+I.

  2. To open the Configuration Parameters dialog box for the referenced model, select the Model block. Then, in the Property Inspector, expand the Solver section and click the hyperlink next to the Use local solver parameter.

  3. Configure the model to use a local solver when referenced in a model hierarchy. In the Configuration Parameters dialog box, on the Model Referencing pane, select Use local solver when referencing model.

  4. Select the fixed-step ode3 as the local solver. On the Solver pane, from the Type list, select Fixed-step. Then, from the Solver list, select ode3 (Bogacki-Shampine).

  5. Set the local solver step size to 0.4 seconds. On the Solver pane, expand Solver details. Then, in the Fixed-step size (fundamental sample time) box, enter 0.4.

  6. Click OK.

Alternatively, use the set_param function to configure the parameters.

set_param(refmdl,UseModelRefSolver="on",...
    SolverType="Fixed-Step",Solver="ode3",FixedStep="0.4")

In the top model, the Model block indicates the local solver you specify.

The solver name ode3 is on the bottom of the Model block icon.

When the local solver step size is larger than the parent solver step size, inherit the communication step size by specifying the Communication step size parameter as -1. The communication step size specifies when the parent solver and local solver exchange data and is registered as a discrete sample time in the parent model.

set_param(topmdl + "/Model",CommunicationStepSize="-1")

Simulate the model, using the local solver to compute the response of the second-order system.

out = sim(topmdl,StopTime="20");

To view the simulation results, open the Simulation Data Inspector. On the Simulation tab, under Review Results, click Data Inspector. Alternatively, call the Simulink.sdi.view function.

Simulink.sdi.view

Plot the signals named System Response and System Response - Top on separate subplots. Alternatively, use the Simulink.sdi.loadView function to load the view named SlowSecondOrderSystem, which was created for this example.

Simulink.sdi.loadView("SlowSecondOrderSystem.mldatx");

Two subplots in the Simulation Data Inspector display the system response. The top plot shows the system response logged inside the referenced model, and the bottom plot shows the system response logged from the top model.

The System Response and System Response - Top signals are the same signal, logged in different locations. The System Response signal is logged inside the referenced model at a rate determined by the local solver step size. The System Response - Top signal is logged by the Outport block in the top model at a rate determined by the top solver step size. Fewer data points are logged for the System Response signal because the local solver step size is larger than the parent solver step size.

Extended Examples

Component-Based Modeling with Model Reference

Component-Based Modeling with Model Reference

Walks you through simulation and code generation of a model that references another model multiple times.

Convert Subsystem to Referenced Model

Convert Subsystem to Referenced Model

Convert a subsystem to a referenced model by using the Model Reference Conversion Advisor or the Simulink.SubSystem.convertToModelReference function.

Reuse Model Components from Files

Reuse Model Components from Files

Save components in separate subsystem and model files.

Improve Simulation Performance by Using Local Solvers

Improve Simulation Performance by Using Local Solvers

Improve simulation performance by using a local solver for a component with much faster dynamics compared to the rest of the system.

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 (SIL)" | "Processor-in-the-loop (PIL)"

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 a command similar to this command, which generates code for a model named ModelName.

    slbuild("ModelName","ModelReferenceCoderTarget")

  • Top model — The code is generated from the top model with the standalone code interface. Code generation uses a command similar to this command, which generates code for a model named ModelName.

    slbuild("ModelName")

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) | "Schedule Editor"

Example: set_param(gcb,ScheduleRatesWith="Schedule Editor")

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 Configure Instance-Specific Values for Block Parameters in a 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: ParameterArgumentNames
Values: comma-separated parameter names in quotes
Parameter: InstanceParameters
Values: structure with fields Name, Value, Path, and Argument
Data Types: struct

For an example of how to set these programmatic parameters, see Parameterize a Referenced Model Programmatically.

To get the instance parameter names and values for a Model block, query InstanceParameters or ParameterArgumentValues with the get_param function. Do not use ParameterArgumentValues to set the instance-specific values.

Dependencies

To enable this parameter, the referenced model must have MATLAB variables or Simulink.Parameter objects in the model workspace that are configured as model arguments. To configure a variable or object as a model argument, select the Argument property.

Solver

Configure a referenced model to use a local solver by 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 parameter of the referenced model.

When you select Use local solver when referencing model, the software uses a local solver to solve the system implemented in the referenced model as a separate system of differential equations. During simulation, the local solver computes the values of continuous states in the referenced model and the output values for the blocks inside the referenced model.

Using a local solver can facilitate system composition and integration. When you use local solvers, you can solve referenced models in system-level simulations using the same solver and step size used to design and test each model in isolation. Using local solvers can also reduce the number of configuration adjustments you need to make to configuration parameters in referenced models while integrating the model into a larger system.

For some systems, using a local solver can improve simulation performance by allowing you to:

  • Choose a solver that is more appropriate to solve the system in the referenced model

  • Use different step sizes for different components to reduce the number of redundant calculations in systems that have a wide range of dynamics among components.

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 of the referenced model. When you use a local solver, the Solver parameter of the referenced model specifies the solver to use as the local solver.

In some systems, using a different local solver can improve simulation performance. For example, when the system is not stiff but the component implemented by the referenced model is stiff, using a stiff local solver can improve performance when simulating the system.

The top solver can be a variable-step or fixed-step solver. The local solver must be a fixed-step solver.

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

Dependencies

To enable this parameter, select Use local solver when referencing model in the 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 step size you specify for the local solver is not registered as a discrete rate in either the referenced model or the parent model.

The local step size can be greater than, less than, or equal to the parent solver step size. However, the communication step size, which determines when the local and parent solvers exchange data, constrains possible values for the local step size.

  • The local step size must be less than or equal to the communication step size.

  • When the local step size is smaller than the communication step size, the local step size must be an integer divisor of the communication step size.

    For example, when the communication step size is 0.1 seconds, the local solver can be an integer divisor such as 0.1 seconds, 0.05 seconds, 0.025 seconds, and so on.

Before R2024a: When the parent solver is a fixed-step solver, the local solver step size must be an integer multiple of the parent solver step size.

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

Dependencies

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

Model Block Parameters

The communication step size specifies the rate at which the local and parent solvers exchange data. The communication step size is registered as a discrete sample time of the Model block in the parent model. By default, the communication step size is inherited (-1) and determined by the software.

When you explicitly specify the communication step size, the value you specify must satisfy all of these constraints:

  • The communication step size must be:

    • Greater than or equal to both the local step size and the parent step size

    • An integer multiple of both the local step size and the parent step size

    • Greater than or equal to the fastest discrete rate in the referenced model

  • Every discrete rate in the referenced model must be evenly divisible by the communication step size.

When the local step size is larger than the parent step size, specify the communication step size as inherited (-1) or equal to the local step size. For example, if the parent step size is 1 second and the local step size is 2 seconds, specify the communication step size as -1 (inherited) or 2. Specifying the communication step size as a larger value, such as 4, could reduce accuracy without providing any performance improvement.

Programmatic Use

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

Parameter: CommunicationStepSize
Values: -1 (default) | positive scalar double
Data Types: double

Example: set_param(gcb,CommunicationStepSize="0.5")

The local solver computes continuous state values and block output values by extrapolating continuous derivative or input signal values that come from the parent solver. This parameter specifies the method the local solver uses to extrapolate continuous derivative or input signal values to the local simulation time.

  • Auto — The software determines the extrapolation method based on the selected solver, the model structure, and how the local step size compares to the parent solver step size.

    The local solver extrapolates input signal values to the local simulation time using a zero-order hold when:

    • You select an implicit solver, such as ode1be or ode14x.

    • The referenced model has no input ports.

    • The local step size is smaller than the parent step size.

    Otherwise, the local solver extrapolates continuous derivatives to the local simulation time using an extrapolation algorithm that is appropriate for the selected solver. The extrapolation algorithms generally improve the accuracy of simulation results but are more computationally intensive than the zero-order hold extrapolation.

    Before R2024a: The software determines how to extrapolate continuous derivative or input signal values based only on the selected solver, and the local step size is always greater than or equal to the parent solver step size.

  • Zero-Order Hold — The local solver extrapolates input signal values to the local simulation time using a zero-order hold. Each input signal value at the local simulation time is equal to the value the parent solver calculated for the signal at the most recent communication step.

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

The local solver propagates time independently during the local solver advance phase that occurs when the parent solver executes the update method for the Model block. Because the update method executes before the advance method in the parent solver simulation loop:

  • The local solver advance occurs before the parent solver advance.

  • The local solver gets ahead of the parent solver in simulation time.

To compute the continuous state values and block output values inside the referenced model, the local solver extrapolates the values for continuous derivatives or input signals to the local simulation time. For more information, see Use Local Solvers in Referenced Models.

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

The local solver might need to provide values for output signals on the model reference interface at the parent solver simulation time. To provide the output signal values, the local solver interpolates continuous state values that affect the output signal values or interpolates the output signal values themselves. This parameter specifies how the local solver interpolates the continuous state or output signal values.

  • Auto — The software determines the interpolation method based on how the local step size compares to the communication step size. (since R2024a)

    • When the local step size is smaller than the communication step size, the local solver interpolates the output signal values to the parent solver simulation time using a zero-order hold.

    • When the local step size is greater than or equal to the communication step size, the local solver interpolates continuous state values to the parent solver simulation time using the local solver interpolant. The local solver then computes the output signal values for the parent solver simulation time using the interpolated continuous state values.

  • Use solver interpolant — The local solver interpolates continuous state values to the parent solver simulation time using the local solver interpolant. This option is supported only when the local step size is greater than or equal to the parent solver step size.

  • Zero-order hold — The local solver interpolates output signal values to the parent solver simulation time using a zero-order hold.

Using the solver interpolant for interpolation generally increases accuracy but also increases computational complexity. Zero-order hold output handling reduces computational complexity but also reduces accuracy.

The local solver propagates time independently during the local solver advance phase that occurs when the parent solver executes the update method for the Model block. Because the update method executes before the advance method in the simulation loop for the parent solver:

  • The local solver advance occurs before the parent solver advance.

  • The local solver gets ahead of the parent solver in simulation time.

To compute output signal values to provide to the parent solver, the local solver interpolates either the values of continuous states that are used in the Model block output method or the output signal values to the parent solver simulation time. For more information, see Use Local Solvers in Referenced Models.

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: "Auto" (default) | "Use solver interpolant" | "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

See Also

| | |

Topics