Main Content

Simulink.FindOptions

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. Enclose each property name in single quotes.

example

Properties

expand all

Option to consider case when matching, specified as the comma-separated pair consisting of 'CaseSensitive' and true or false.

Data Types: logical

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.

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

Option to include commented blocks in the search, specified as the comma-separated pair consisting of 'IncludeCommented' and true or false.

Data Types: logical

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.

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

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

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

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

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 — 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 the Variants argument.

  • Simulink.match.legacy.filterOutInactiveVariantSubsystemChoices — Filter function to find active Variant Subsystem choice blocks. 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

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'                         }
Open Live Script

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)));
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 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 R2018a

expand all

See Also

| |