Simulink.FindOptions

R2026b

Specify options for finding blocks in models and subsystems

expand all in page

Description

Simulink.FindOptions objects allow you to constrain a search with the Simulink.findBlocks and Simulink.findBlocksOfType functions.

Creation

Syntax

f = Simulink.FindOptions
f = Simulink.FindOptions(Name=Value)

Description

f = Simulink.FindOptions creates a FindOptions object that uses the default search options.

f = Simulink.FindOptions(Name=Value) sets properties using name-value pairs. For example, Simulink.FindOptions(SearchDepth=1) creates a FindOptions object with a search depth of 1. You can specify multiple name-value pairs.

example

Properties

expand all

Option to consider case when matching. To turn the option on, specify true. To turn the option off, specify false.

Data Types: logical

Option to look inside referenced subsystems in a model and list child blocks. To turn the option on, specify true. To turn the option off, specify false.

Data Types: logical

Option to search inside referenced models in a model and list child blocks. To turn the option on, specify true. To turn the option off, specify false.

Data Types: logical

Option to search inside library links. To turn the option on, specify true. To turn the option off, specify false.

If you do not specify a model to search, the find_system function includes loaded libraries in the results regardless of whether specify true or false. You can use SearchInsideLibraryLinks with SearchUnderMasks to update library links in subsystems. See Update Library Links in a Subsystem.

Data Types: logical

Option to include commented blocks in the search. To turn the option on, specify true. To turn the option off, specify false.

Data Types: logical

Option to load any partially loaded models. To turn the option on, specify true. To turn the option off, specify false. Use this option, for example, to prevent load warnings.

Data Types: logical

Options for searching under masks, specified as one of these values:

  • "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: string | char

Option to treat search expressions as regular expressions. To turn the option on, specify true. To turn the option off, specify false.

When you turn the option on, the search treats search expressions as regular expressions. To learn more about MATLAB® regular expressions, see Regular Expressions.

Data Types: logical

Option to restrict the search depth to the specified level, specified as a positive integer. Format the value as a numeric scalar, string, or character vector.

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

Note

The Variants argument will be removed. Use MatchFilter instead. For more information, see Version History.

Options for searching variants, specified as 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 are 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: string | char

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

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 — Include in the search the blocks inside the choices of a variant subsystem that are active in simulation and are part of the generated code. This function produces similar results as the 'ActivePlusCodeVariants' option of the Variants argument.

  • Simulink.match.legacy.filterOutInactiveVariantSubsystemChoices — Include in the search the blocks inside the active choice of a variant subsystem. This function produces similar results as the 'ActiveVariants' option of the Variants 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 or label

    • 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, and Simulink.FindOptions.

To operate on all types of variant blocks, use the Simulink.match.codeCompileVariants or Simulink.match.activeVariants filters after model compilation.

Examples

collapse all

Suppose you have a loaded model named myModel. The model contains masked subsystems. Get the handles of all Transfer Fcn blocks in the model, excluding blocks in the masked subsystems.

Create a FindOptions object that specifies you want to exclude the content of masked subsystems in the search.

f = Simulink.FindOptions(SearchUnderMasks="none");

Get the block handles.

h = Simulink.findBlocksOfType("myModel","TransferFcn",f);

Suppose you have a loaded model named myModel. The model contains subsystems and other components. Get the handles of all Transfer Fcn blocks in the top level of the model.

Get the model handle.

hModel = get_param("myModel","Handle");

Create a FindOptions object that specifies you want to exclude the content of masked subsystems in the search.

f = Simulink.FindOptions(SearchDepth=1);

Get the block handles.

h = Simulink.findBlocks(hModel,f);
Open Live Script

You can use the MatchFilter argument to specify which elements to include in the search, as defined by a custom filter function.

For example, to find all Gain blocks in a model with a gain value between 1 and 10, define a custom filter function as shown in the file gainOneToTen.m. This function checks each block and returns true only for Gain blocks whose gain value is within the specified range.

type 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

To apply this filter to the slexVariantSourceAndSink model, provide the function handle as the value for the MatchFilter argument in the Simulink.FindOptions object. Then, use the object with the Simulink.findBlocks function.

load_system("slexVariantSourceAndSink");
findOptObj = Simulink.FindOptions("MatchFilter",@gainOneToTen);
blks = getfullname((Simulink.findBlocks("slexVariantSourceAndSink",findOptObj)))
blks = 4×1 cell
    {'slexVariantSourceAndSink/Gain2'}
    {'slexVariantSourceAndSink/Gain3'}
    {'slexVariantSourceAndSink/Gain4'}
    {'slexVariantSourceAndSink/Gain5'}
Open Live Script

Load the slexVariantSubsystems model.

model = 'slexVariantSubsystems';
load_system(model);
assignin('base','VSS_MODE',2);

Use the MatchFilter option with Simulink.match.activeVariants to find blocks that are active in simulation after model compilation.

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 blocks that are part of the generated C code after model compilation.

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 edit-time filter function Simulink.match.legacy.filterOutCodeInactiveVariantSubsystemChoices to include in the search the blocks inside the choices of a variant subsystem that are active in simulation and are part of the generated code. 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 edit-time filter function Simulink.match.legacy.filterOutInactiveVariantSubsystemChoices to include in the search the blocks inside the active choice of a variant subsystem. 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)));

Find the Variant Subsystem blocks in the model.

findOpts = Simulink.FindOptions('MatchFilter',@Simulink.match.legacy.filterOutInactiveVariantSubsystemChoices);
blksVSS = getfullname((Simulink.findBlocks(model,'BlockType','SubSystem','Variant','on',findOpts)));

Version History

Introduced in R2018a

expand all

See Also

| |