find_mdlrefs

Find referenced models and Model blocks in model hierarchy

Syntax

[models,blocks] = find_mdlrefs(system)

[models,blocks] = find_mdlrefs(system,Name,Value)

Description

[models,blocks] = find_mdlrefs(system) finds all referenced models and Model blocks in the model hierarchy below the specified system. The find_mdlrefs function temporarily loads the models.

[models,blocks] = find_mdlrefs(system,Name,Value) provides additional search options using one or more name-value pairs. For example, to keep the models loaded instead of temporarily loading them, set KeepModelsLoaded to true.

Examples

Find Referenced Models in Model Hierarchy

Find referenced models and Model blocks for all models referenced by the specified model.

load_system('sldemo_mdlref_basic');
[myModels,myModelBlks] = find_mdlrefs('sldemo_mdlref_basic')

myModels = 2x1 cell
    {'sldemo_mdlref_counter'}
    {'sldemo_mdlref_basic'  }

myModelBlks = 3x1 cell
    {'sldemo_mdlref_basic/CounterA'}
    {'sldemo_mdlref_basic/CounterB'}
    {'sldemo_mdlref_basic/CounterC'}

Find and Load All Models in Model Hierarchy

By default, the find_mdlrefs function loads and then closes the models that were not already loaded. To identify what models are loaded, use the find_system function.

find_mdlrefs('sldemo_mdlref_depgraph');
find_system('type','block_diagram')

ans =

  0x1 empty cell array

To find and load all models in the model hierarchy, set KeepModelsLoaded to true.

find_mdlrefs('sldemo_mdlref_depgraph','KeepModelsLoaded',true);
find_system('type','block_diagram')

ans = 8x1 cell
    {'sldemo_mdlref_thermostat'  }
    {'sldemo_mdlref_heater'      }
    {'sldemo_mdlref_F2C'         }
    {'sldemo_mdlref_outdoor_temp'}
    {'sldemo_mdlref_house'       }
    {'sldemo_mdlref_heat2cost'   }
    {'simulink_extras'           }
    {'sldemo_mdlref_depgraph'    }

The top model and all referenced models remain loaded. If you open sldemo_mdlref_depgraph, you can navigate the model hierarchy without waiting for the referenced models to load as you open them.

Input Arguments

system — System name, block path, or handle

character vector | string scalar | numeric scalar

System name, block path, or handle, specified as a character vector, string scalar, or numeric scalar.

The system must be an SLX file, MDL file, Model block, or Subsystem block.

If you specify a file name, do not include the file extension.

Data Types: double | char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: refModels = find_mdlrefs(topmodel,'KeepModelsLoaded',true,'ReturnTopModelAsLastElement',false)

KeepModelsLoaded — Option to keep models loaded

false or 0 (default) | true or 1

Option to keep models loaded, specified as the comma-separated pair consisting of 'KeepModelsLoaded' and a numeric or logical 1 (true) or 0 (false).

By default the function loads and then closes the models that were not already loaded. To keep the models loaded, set this argument to true. Keeping the models loaded can be useful if you plan on interacting with the models after finding them.

Data Types: logical

AllLevels — Levels to search

true or 1 (default) | false or 0

Levels to search, specified as the comma-separated pair consisting of 'AllLevels' and a numeric or logical 1 (true) or 0 (false).

• true — Search all Model blocks in the model hierarchy of the specified system.

• false — Search only the top-level system.

Data Types: logical

IncludeProtectedModels — Option to include protected models

false or 0 (default) | true or 1

Option to include protected models in the search results, specified as the comma-separated pair consisting of 'IncludeProtectedModels' and a numeric or logical 1 (true) or 0 (false).

This setting only affects the returned list of referenced models; It does not affect the returned list of Model blocks.

Data Types: logical

IncludeCommented — Option to include commented blocks

false or 0 (default) | true or 1

Option to include commented blocks in the search results, specified as the comma-separated pair consisting of 'IncludeCommented' and a numeric or logical 1 (true) or 0 (false).

Data Types: logical

CaseSensitive — Option to match case when searching

true (default) | false

Option to match case when searching, specified as true for case-sensitive search or false for case-insensitive search.

Data Types: logical

FollowLinks — Option for search to follow library links

true (default) | false

Option for the search to follow library links, specified as true or false. If true, search follows links into library blocks.

Data Types: logical

LookUnderMasks — Options to search masked blocks

'all' (default) | 'none' | 'functional' | 'graphical'

Options to search masked blocks, specified as:

• 'all' — Search in all masked blocks.

• 'none' — Prevent searching in masked systems.

• 'functional' — Include masked subsystems that do not have dialogs.

• 'graphical' — Include masked subsystems that do not have workspaces or dialogs.

Data Types: char | string

MatchFilter — Option to match and filter elements in search

function handle

Option to match and filter elements such as blocks, system, lines, ports, and annotations in a search, specified as function handle. Use MatchFilter to determine whether elements should be included or skipped in the search.

The argument:

• Allows you to filter elements with custom filter functions

• Avoids processing elements when filters do not match

• Applies complex filters on blocks, lines, or annotations, to filter the results internally

The named function must be defined within a MATLAB^® program file. The function takes the handle of the element as input and returns two outputs.

 function [match, prune] = func(element)

• The input element is the handle of the block being processed.

• The first output, match, is a logical value. If false, search skips the element.

• The second output, prune, is an optional logical value that only applies when element is a subsystem. The default value is false. If this value is set to true, the entire subsystem is omitted from the search.

For example, use MatchFilter to find all Model blocks in a model for which the InitFcn callback is defined, using the filter function initFcnMdlBlocks:

function match = initFcnMdlBlocks(handle)
  match = ~isempty(get_param(handle,'InitFcn'));
end

openExample('simulink_variants/SimulinkVariantsExample');
model='slexVariantMdlRefCondProp';
load_system(model);
[models,blocks] = find_mdlrefs(model,'MatchFilter',@initFcnMdlBlocks)

Variants: Simulink^® provides these built-in match filter functions to find variant blocks that are active in simulation or part of the generated code.

• Simulink.match.activeVariants — Filter function to find blocks that are active in simulation after model compilation.

• Simulink.match.codeCompileVariants — Filter function to find blocks that are part of generated code after model compilation.

• Simulink.match.allVariants — Filter function to find all blocks irrespective of whether the block is active or inactive due to variants.

Note

To get correct results, you must compile the model before using Simulink.match.activeVariants and Simulink.match.codeCompileVariants filters. If the model is not compiled, these filters return all blocks in the model.

For example, use the Simulink.match.activeVariants option to find active variants in a model.

openExample('simulink_variants/SimulinkVariantsExample');
model='slexVariantMdlRefCondProp';
load_system(model);
set_param(model,'SimulationCommand','update');
[models,blocks] = find_mdlrefs(model,'MatchFilter',@Simulink.match.activeVariants);

For example, use the Simulink.match.codeCompileVariants option to find variant choices that are part of the generated C code.

openExample('simulink_variants/SimulinkVariantsExample');
load_system('slexVariantMdlRefCondProp');
assignin('base','VSS_MODE',2);
slexVariantMdlRefCondProp([],[],[],'compileForCodegen');
[models,blocks] = find_mdlrefs('slexVariantMdlRefCondProp',...
                               'MatchFilter',@Simulink.match.codeCompileVariants);
slexVariantMdlRefCondProp([],[],[],'term');

Example: Use the Simulink.match.allVariants() filter to find all blocks in a model.

openExample('simulink_variants/SimulinkVariantsExample');
model='slexVariantMdlRefCondProp';
load_system(model);
[models,blocks]=find_mdlrefs(model,'MatchFilter',@Simulink.match.allVariants);

Variants — Option to include variant models

'ActivePlusCodeVariants' (default) | 'ActiveVariants' | 'AllVariants'

Note

The Variants argument will be removed. Use MatchFilter instead. For more information, see Compatibility Considerations.

Option to include variant models in the search results, specified as the comma-separated pair consisting of 'Variants' and 'ActivePlusCodeVariants', 'ActiveVariants', or 'AllVariants'.

• 'ActivePlusCodeVariants' — Include all variant models in the Variant Subsystem that are active in simulation and is part of the generated code.

• 'ActiveVariants' — Include the active variant models in the Variant Subsystem block.

• 'AllVariants' — Include all variant models in the Variant Subsystem block.

This search constraint applies only to Variant Subsystem blocks that have the Variant control mode set to expression or label. Use the find_mdlrefs function with the MatchFilter option to operate on all types of variant blocks.

Data Types: char | string

ReturnTopModelAsLastElement — Option to include specified system

true or 1 (default) | false or 0

Option to include the specified system in the search results, specified as the comma-separated pair consisting of 'ReturnTopModelAsLastElement' and a numeric or logical 1 (true) or 0 (false).

By default, the last element in the returned list of referenced models is the name of the model, library, or subsystem file that you specified with the system argument. If you specify a block, the last element is the name of the file that contains it.

Data Types: logical

Output Arguments

models — Names of models

cell array of character vectors

Names of models, returned as a cell array of character vectors.

By default, the last element is the name of the model, library, or subsystem file that you specified with the system argument. If you specify a block, the last element is the model, library, or subsystem file that contains it.

blocks — Names of Model blocks

cell array of character vectors

Names of Model blocks, returned as a cell array of character vectors.

Version History

Introduced before R2006a

R2022b: Warnings for removal of Variants argument

As part of the removal of the Variants argument in a future release, these warnings have been introduced:

• When you use the find_mdlrefs function without the Variants argument, the function generates a warning if it skips the inactive choice of a Variant Subsystem block during the search.

  Consider a model with a Variant Model block that has two variant choices, Mdl_Linear_Controller and Mdl_NonLinear_Controller. The Mdl_NonLinear_Controller block is the active choice.

  This command skips the inactive Mdl_Linear_Controller block and generates a warning.

  [myModels,myModelBlks] = find_mdlrefs...
  ('sldemo_variant_subsystems_modelblocks')

  Warning: Using find_mdlrefs without the 'Variants' argument skips inactive Variant Subsystem blocks in the
  search. This behavior will change in a future release to look at all choices of the Variant Subsystem. To find
  blocks that are active in simulation or code generation, compile the model and use the built-in variant filters
  with the 'MatchFilter' option. 
  myModels =
  
    2×1 cell array
  
      {'mdlref_nonlinear_controller'          }
      {'sldemo_variant_subsystems_modelblocks'}
  
  
  myModelBlks =
  
    1×1 cell array
  
      {'sldemo_variant_subsystems_modelblocks/Controller/Mdl_NonLinear_Controller'}

• When you use the Variants argument with its value set to 'AllVariants', the function generates a warning.

  [myModels,myModelBlks] = find_mdlrefs...
  ('sldemo_variant_subsystems_modelblocks','Variants','AllVariants')

  Warning: 'Variants' will be removed. Instead of using 'Variants' with value set to 'AllVariants',
  use 'MatchFilter' with value set to @Simulink.match.allVariants.
  myModels =
  
    3×1 cell array
  
      {'Linear_Controller'                    }
      {'Nonlinear_Controller'                 }
      {'sldemo_variant_subsystems_modelblocks'}
  
  
  myModelBlks =
  
    2×1 cell array
  
      {'sldemo_variant_subsystems_modelblocks/Controller/Linear Controller'   }
      {'sldemo_variant_subsystems_modelblocks/Controller/Nonlinear Controller'}

R2022a: New built-in match filter to find all variant blocks

You can use the built-in match filter, Simulink.match.allVariants, to find all the blocks in a variant model regardless of whether the block is active or inactive due to variants. This filter is the recommended replacement for the AllVariants option.

To be removed	Recommended Replacement
find_mdlrefs(model,'Variants','AllVariants');	find_mdlrefs(model,'MatchFilter', ... @Simulink.match.allVariants);

R2021a: Default behavior has changed for Variants and MatchFilter arguments in model with variant blocks

• Variants: When you use the find_mdlrefs function without the Variants argument, for Variant Subsystem blocks, the function currently includes only those choices that are active during simulation or code generation in the search by default.

  For other variant blocks such as Variant Source, Variant Sink, or Variant Subsystem blocks with the Propagate conditions outside of variant subsystem parameter set to on, the function includes all choices in the search.

  Consider a model with a Variant Model block that has two variant choices, Mdl_Linear_Controller and Mdl_NonLinear_Controller.

  This command returns only the active Model blocks in the model.

  [myModels,myModelBlks] = find_mdlrefs...
  ('sldemo_variant_subsystems_modelblocks')

  myModels =
  
    2×1 cell array
  
      {'mdlref_nonlinear_controller'          }
      {'sldemo_variant_subsystems_modelblocks'}
  
  
  myModelBlks =
  
    1×1 cell array
  
      {'sldemo_variant_subsystems_modelblocks/Controller/Mdl_NonLinear_Controller'}

• MatchFilter: When you use the find_mdlrefs function with the MatchFilter argument, the function applies the filters on the active and inactive variant choices by default.

  Consider a model with a Variant Model block that has two variant choices, Mdl_Linear_ Controller and Mdl_NonLinear_Controller. The filter function initFcnMdlBlocks finds all the Model blocks for which the InitFcn callback is set.

   function match = initFcnMdlBlocks(handle)
   match = ~isempty(get_param(handle, 'InitFcn'));
   end

  This command returns the active and inactive Model blocks in the model.

  [myModels,myModelBlks] = find_mdlrefs('sldemo_variant_subsystems_modelblocks',...
   'MatchFilter', @initFcnMdlBlocks)

  myModels =
  
    3×1 cell array
  
      {'mdlref_linear_controller'             }
      {'mdlref_nonlinear_controller'          }
      {'sldemo_variant_subsystems_modelblocks'}
  
  
  myModelBlks =
  
    2×1 cell array
  
      {'sldemo_variant_subsystems_modelblocks/Controller/Mdl_Linear_Controller'   }
      {'sldemo_variant_subsystems_modelblocks/Controller/Mdl_NonLinear_Controller'}

R2021a: Variants argument will be removed

The Variants argument will be removed from find_mdlrefs in a future release. Function calls that use the Variants argument continue to work with a warning.

Using the find_mdlrefs function with the Variants argument produces inconsistent search results. The find_mdlrefs function is an edit-time operation, but to determine whether a block is active in a model with all types of variant blocks, you need to compile the model.

To find Model blocks that are active during simulation or code generation, compile the model and use the find_mdlrefs function with the MatchFilter argument.

This table lists the recommended replacement for different values of the Variants argument.

To Be Removed	Recommended Replacement
find_mdlrefs(model,'Variants', ... 'ActiveVariants');	set_param(model,'SimulationCommand','update'); find_mdlrefs(model,'MatchFilter', ... @Simulink.match.activeVariants);
find_mdlrefs(model,'Variants', ... 'ActivePlusCodeVariants');	model([],[],[],'compileForCodegen'); [models,blocks] = find_mdlrefs(model,'MatchFilter', ... @Simulink.match.codeCompileVariants); model([],[],[],'term');

When you use the find_system function, you cannot specify both of the MatchFilter and Variants arguments.

This command produces an error.

find_mdlrefs(bdroot,'MatchFilter',@Simulink.match.activeVariants,...
    'Variants','ActiveVariants');

R2020b: Filter elements during search with MatchFilter

To match and filter model elements during a search, you can define a custom filter function and pass the function handle as value to the MatchFilter name-value argument.

To find variant blocks that are active in a simulation or part of the generated code, you can use the built-in match filter functions, Simulink.match.activeVariants, Simulink.match.codeCompileVariants, and Simulink.match.allVariants, after compiling the model.

R2020b: Specifying a logical value as the second argument of find_mdlrefs is discouraged

The find_mdlrefs function provides two ways to specify whether to search all levels of the model hierarchy. Both techniques give the same results, but only the name-value pair technique allows you to specify additional options.

Instead of specifying whether to search all levels of the model hierarchy with a logical as the second argument, use the AllLevels name-value pair.