Simulink.FindOptions
Specify options for finding blocks in models and subsystems
Description
Simulink.FindOptions
objects allow you to constrain a search
with the Simulink.findBlocks
and
Simulink.findBlocksOfType
functions.
Creation
Description
creates a
f
= Simulink.FindOptionsFindOptions
object that uses the default search
options.
sets properties using name-value pairs. For example,
f
= Simulink.FindOptions(Name,Value
)Simulink.FindOptions('SearchDepth',1)
creates a
FindOptions
object with a search depth of
1
. You can specify multiple name-value pairs. Enclose
each property name in single quotes.
Properties
CaseSensitive
— Search criteria option to consider case when matching
true
(default) | false
Option to consider case when matching, specified as the comma-separated
pair consisting of 'CaseSensitive'
and
true
or false
.
Data Types: logical
LookInsideSubsystemReference
— Search criteria option to look inside a referenced subsystem
true
(default) | false
Option to look inside a referenced subsystem in a model and list child
blocks specified as the comma-separated pair consisting of
'LookInsideSubsystemReference'
and
true
or false
.
FollowLinks
— Search criteria option to follow links into library blocks
false
(default) | true
Option to follow links into library blocks, specified as the
comma-separated pair consisting of 'FollowLinks'
and
true
or false
. If you do not
specify a model to search, find_system
includes loaded
libraries in the results, whether you set 'FollowLinks'
to true
or false
. You can use
'FollowLinks'
with
'LookUnderMasks'
to update library links in
subsystems. See Update Library Links in a Subsystem.
Data Types: logical
IncludeCommented
— Search criteria option to include commented blocks
true
(default) | false
Option to include commented blocks in the search, specified as the
comma-separated pair consisting of 'IncludeCommented'
and
true
or false
.
Data Types: logical
LoadFullyIfNeeded
— Search criteria option to load any partially loaded models
true
(default) | false
Option to load any partially loaded models, specified as the
comma-separated pair of 'LoadFullyIfNeeded'
and
true
to load models or false
to
disable loading. Use this option, for example, to prevent load
warnings.
LookUnderMasks
— Search criteria options for searching under masks
'all'
(default) | 'none'
| 'functional'
| 'graphical'
Options for searching under masks, specified as the comma-separated pair
consisting of 'LookUnderMasks'
and one of these options:
'none'
— Search skips masked subsystems.'all'
— Search includes all masked subsystems.'functional'
— Search includes masked subsystems that has icon drawing commands or mask initialization commands without having parameters, description,help strings, and UI elements'graphical'
— Search includes masked subsystems that has only icon drawing commands without having workspaces, dialogs, help strings, and UI elements.
Data Types: char
| string
RegExp
— Search criteria option to treat search expressions as regular expressions
false
(default) | true
Option to treat search expressions as regular expressions specified as the
comma-separated pair consisting of 'RegExp'
and
true
or false
. When
'RegExp'
is set to true
, the
search treats search expressions as regular expressions. To learn more about
MATLAB® regular expressions, see Regular Expressions.
Data Types: logical
SearchDepth
— Search criteria option to restrict the search depth
-1
(default) | positive integer
Option to restrict the search depth to the specified level, specified as
the comma-separated pair consisting of 'SearchDepth'
and
a positive integer character vector or string scalar. For example, specify
0
to search loaded models only, 1
for blocks and subsystems of the top level of the model
hierarchy,2
for the top level of the model hierarchy
and its children, etc. The default value -1
is to search
all levels.
Data Types: int32
Variants
— Search criteria options for searching variants
'AllVariants'
(default) | 'ActiveVariants'
| 'ActivePlusCodeVariants'
Note
The Variants
argument will be removed. Use
MatchFilter
instead. For more information, see
Version History.
Options for searching variants, specified as the comma-separated pair
consisting of 'Variants'
and one of these options:
'ActiveVariants'
— Search only the active variant choice in the Variant Subsystem.'AllVariants'
— Search all variant choices in the Variant Subsystem.'ActivePlusCodeVariants'
— Search all variant choices in the Variant Subsystem that are active in simulation and is part of the generated code.
This search constraint applies only to Variant Subsystem
blocks that have the Variant control mode set to
expression
or label
. Use the
find_system
function with the
MatchFilter
option to operate on all types of
variant blocks.
Data Types: char
| string
MatchFilter
— Search criteria option to match and filter elements in search
function handle
Option to match and filter elements such as blocks, model, lines, ports,
and annotations in a search, specified as function handle. Use
MatchFilter
to determine whether elements should be
included or skipped in a 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 component being processed, for example the block handle.The first output,
match
, is a logical value. Iffalse
, search skips the element.The second output,
prune
, is an optional logical value that only applies whenelement
is a subsystem. The default value isfalse
. If this value is set totrue
, the entire subsystem is omitted from the search.
Variants: Simulink® provides these built-in match filter functions to find variant blocks.
Post-compile time filter functions:
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 an example that compares the pre-compile and post-compile time results for these filters, see Compare Pre-Compile and Post-Compile Behavior of Match Filters for Variant Blocks.
Edit-time filter functions for Variant Subsystem blocks:
Simulink.match.legacy.filterOutCodeInactiveVariantSubsystemChoices
— Filter function to find Variant Subsystem choice blocks that are active in simulation or part of generated code. This function produces similar results as the'ActivePlusCodeVariants'
option of theVariants
argument.Simulink.match.legacy.filterOutInactiveVariantSubsystemChoices
— Filter function to find active Variant Subsystem choice blocks. This function produces similar results as the'ActiveVariants'
option of theVariants
argument.
Limitations of edit-time filters:
The filters do not use the post-compile block activeness information in the CompiledVariantInfo block parameter.
The filters apply only to Variant Subsystem blocks that have these block parameter settings:
Variant control mode set to
expression
orlabel
Propagate conditions outside of variant subsystem set to
off
The filters can identify if a block handle is inside the active choice of a Variant Subsystem only when used within the context of
find_system
,find_mdlrefs
, andSimulink.FindOptions
.
To operate on all types of variant blocks, use the
Simulink.match.codeCompileVariants
or
Simulink.match.activeVariants
filters after model
compilation.
Examples
Specify Search Options
Create a Simulink.FindOptions
object that specifies a
search depth of 1
.
f = Simulink.FindOptions('SearchDepth',1);
Using the FindOptions
object, search for all blocks in
the subsystem named Unlocked
, but not in any of its
children.
openExample('sldemo_clutch'); bh = Simulink.findBlocks('sldemo_clutch/Unlocked',f);
The Simulink.findBlocks
function returns the block
handles.
To get the block path, use the getfullname
function.
bp = getfullname(bh)
bp = 20×1 cell array {'sldemo_clutch/Unlocked/Tfmaxk' } {'sldemo_clutch/Unlocked/Tin' } {'sldemo_clutch/Unlocked/Enable' } {'sldemo_clutch/Unlocked/E_Sum' } {'sldemo_clutch/Unlocked/Engine↵Damping' } {'sldemo_clutch/Unlocked/Engine↵Inertia' } {'sldemo_clutch/Unlocked/Engine↵Integrator' } {'sldemo_clutch/Unlocked/Goto' } {'sldemo_clutch/Unlocked/Goto1' } {'sldemo_clutch/Unlocked/Max↵Dynamic↵Friction↵Torque'} {'sldemo_clutch/Unlocked/V_Sum' } {'sldemo_clutch/Unlocked/Vehicle↵Damping' } {'sldemo_clutch/Unlocked/Vehicle↵Inertia' } {'sldemo_clutch/Unlocked/Vehicle↵Integrator' } {'sldemo_clutch/Unlocked/W_Slip' } {'sldemo_clutch/Unlocked/slip direction' } {'sldemo_clutch/Unlocked/w0' } {'sldemo_clutch/Unlocked/w0 ' } {'sldemo_clutch/Unlocked/we' } {'sldemo_clutch/Unlocked/wv' }
Specify Search Options with Custom Filter Functions
Use the MatchFilter
option with a custom filter function to find all Gain blocks with a gain value between 1
and 10
in the model vdp
.
The custom function is defined in the file gainOneToTen.m
.
function match = gainOneToTen(blk) match = false; if strcmp(get_param(blk,'Type'),'block') ... && strcmp(get_param(blk,'BlockType'),'Gain') gainValue = str2double(get_param(blk,'Gain')); match = gainValue >= 1 && gainValue <= 10; end end
Provide the function handle as the value of the MatchFilter
argument.
load_system('vdp'); findOptObj = Simulink.FindOptions('MatchFilter',@gainOneToTen); blks = getfullname((Simulink.findBlocks('vdp',findOptObj)));
Specify Search Options for Variant Blocks with Built-In Filter Functions
Load the slexVariantSubsystems
model.
model = 'slexVariantSubsystems'; load_system(model); assignin('base','VSS_MODE',2);
Use the MatchFilter
option with Simulink.match.activeVariants
to find active variants in a model.
set_param(model,'SimulationCommand','update'); findOptObj = Simulink.FindOptions('MatchFilter',@Simulink.match.activeVariants); blks = getfullname((Simulink.findBlocks(model,findOptObj)));
Use the MatchFilter
option with Simulink.match.codeCompileVariants
to find variant choices that are part of the generated C code.
slexVariantSubsystems([],[],[],'compileForCodegen'); findOptObj = Simulink.FindOptions('MatchFilter',@Simulink.match.codeCompileVariants); blks = getfullname((Simulink.findBlocks(model,findOptObj))); slexVariantSubsystems([],[],[],'term');
Use the MatchFilter
option with Simulink.match.allVariants
to find all blocks in a model.
findOptObj = Simulink.FindOptions('MatchFilter',@Simulink.match.allVariants);
blks = getfullname((Simulink.findBlocks(model,findOptObj)));
Use the MatchFilter
option with Simulink.match.legacy.filterOutCodeInactiveVariantSubsystemChoices
to find Variant Subsystem choice blocks that are active in simulation or part of generated code at edit-time. For information on the limitations of edit-time filters, see MatchFilter.
findOptObj = Simulink.FindOptions('MatchFilter',@Simulink.match.legacy.filterOutCodeInactiveVariantSubsystemChoices);
blks = getfullname((Simulink.findBlocks(model,findOptObj)));
Use the MatchFilter
option with Simulink.match.legacy.filterOutInactiveVariantSubsystemChoices
to find active Variant Subsystem choice blocks at edit-time. For information on the limitations of edit-time filters, see MatchFilter.
findOptObj = Simulink.FindOptions('MatchFilter',@Simulink.match.legacy.filterOutInactiveVariantSubsystemChoices);
blks = getfullname((Simulink.findBlocks(model,findOptObj)));
Version History
Introduced in R2018aR2022a: 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 |
---|---|
findOptObj= Simulink.FindOptions('Variants', ... 'AllVariants'); |
findOptObj= Simulink.FindOptions('MatchFilter', ... @Simulink.match.allVariants); |
R2021a: Variants
option will be removed
The Variants
option will be removed from
Simulink.FindOptions
in a future release. Scripts that use the
Variants
option continue to work with a warning.
Using the Simulink.FindOptions
object with the
Variants
argument produces inconsistent search results.
Simulink.FindOptions
is used at edit-time, 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 variant blocks that are active during simulation or code generation,
compile the model and use the Simulink.FindOptions
object with the
MatchFilter
option.
This table lists the recommended replacement for different values of the
Variants
option.
To Be Removed | Recommended Replacement |
---|---|
findOptObj= Simulink.FindOptions('Variants', ... 'ActiveVariants'); |
set_param(model,'SimulationCommand','update'); findOptObj= Simulink.FindOptions('MatchFilter', ... @Simulink.match.activeVariants); |
findOptObj= Simulink.FindOptions('Variants', ... 'ActivePlusCodeVariants'); |
model([], [], [], 'compileForCodegen'); findOptObj = Simulink.FindOptions('MatchFilter', ... @Simulink.match.codeCompileVariants); blks=getfullname((Simulink.findBlocks(model,findOptObj))); model([], [], [], 'term'); |
When you use the Simulink.FindOptions
object, you cannot specify
both of the MatchFilter
and Variants
arguments.
This command produces an error.
f = Simulink.FindOptions('MatchFilter',... @Simulink.match.activeVariants, 'Variants', 'ActiveVariants'); blocks=Simulink.findBlocks('sldemo_variant_subsystems',f)
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
option.
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.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)