padv.builtin.query.FindSubsystemsForModel Class

Namespace: padv.builtin.query
Superclasses: padv.Query

Find subsystems associated with specific design model

Description

The padv.builtin.query.FindSubsystemsForModel class provides a query that can return subsystems associated with a specific design model. You can automatically include or exclude certain files by using the optional name-value arguments.

You can use this query in your process model to find models for your tasks to iterate over or use as inputs.

The padv.builtin.query.FindSubsystemsForModel class is a handle class.

Creation

Description

query = padv.builtin.query.FindSubsystemsForModel() creates a query for finding all subsystems in a model. By default, the query returns the subsystems and the root level block diagram for the model. The query determines which models to iterate over by running the parent query and then finding the subsystems in those models.

query = padv.builtin.query.FindSubsystemsForModel(Name=Value) sets certain properties using one or more name-value arguments. For example, padv.builtin.query.FindSubsystemsForModel(ExcludePath="AvgValue") creates a query that finds subsystems, but excludes subsystems where the block path contains "AvgValue".

The padv.builtin.query.FindSubsystemsForModel class also has other properties, but you cannot set those properties during query creation.

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.

Example: padv.builtin.query.FindSubsystemsForModel(ExcludePath="AvgValue")

Name — Unique identifier for query

string | character vector

Unique identifier for query, specified as a string or a character vector.

Example: "FindMySubsystems"

Data Types: char | string

IncludePath — Only include subsystems where block path contains specific text

string

Only include subsystems where the block path contains specific text, specified as a string.

To get the path for a subsystem or block diagram, you can use the function padv.util.getSubsystemPath.

Example: "AvgValue"

Example: "AHRS_Voter/AvgValue"

Data Types: string

ExcludePath — Exclude subsystems where block path contains specific text

string

Exclude subsystems where the block path contains specific text, specified as a string.

To get the path for a subsystem or block diagram, you can use the function padv.util.getSubsystemPath.

Example: "AvgValue"

Example: "AHRS_Voter/AvgValue"

Data Types: string

IncludeBlockNameRegex — Only include subsystems where block name matches regular expression pattern

string

Only include subsystems where the block name matches a regular expression pattern, specified as a string.

Example: "^A.*"

Data Types: string

ExcludeBlockNameRegex — Exclude subsystems where block name matches regular expression pattern

string

Exclude subsystems where the block name matches a regular expression pattern, specified as a string.

Example: "^A.*"

Data Types: string

IncludeRootLevel — Include root level block diagram of model as subsystem

1 (true) (default) | 0 (false)

Include the root level block diagram of model as a subsystem, specified as a numeric or logical 1 (true) or 0 (false).

For example, for the model AHRS_Voter, the query returns the subsystems of the model and the block diagram AHRS_Voter by default.

Data Types: logical

Parent — Initial query that runs before iteration query

padv.Query | Name of padv.Query object

Initial query that runs before iteration query, specified as either a padv.Query object or the Name of a padv.Query object. When you specify an iteration query for a task, the parent query is the initial query that the build system runs before running the specified iteration query.

For information on how to improve Process Advisor load times by sharing query instances across your process model, see Best Practices for Process Model Authoring.

Example: sharedQuery

Example: "FindMyInitialArtifacts"

ShowPath — Display full block path in Process Advisor

0 (false) (default) | 1 (true)

Display full block path in Process Advisor, specified as a numeric or logical 1 (true) or 0 (false).

Data Types: logical

Properties

IncludePath — Only include subsystems where block path contains specific text

string

Only include subsystems where the block path contains specific text, specified as a string.

To get the path for a subsystem or block diagram, you can use the function padv.util.getSubsystemPath.

Example: "AvgValue"

Example: "AHRS_Voter/AvgValue"

Data Types: string

ExcludePath — Exclude subsystems where block path contains specific text

string

Exclude subsystems where the block path contains specific text, specified as a string.

To get the path for a subsystem or block diagram, you can use the function padv.util.getSubsystemPath.

Example: "AvgValue"

Example: "AHRS_Voter/AvgValue"

Data Types: string

IncludeBlockNameRegex — Only include subsystems where block name matches regular expression pattern

string

Only include subsystems where the block name matches a regular expression pattern, specified as a string.

Example: "^A.*"

Data Types: string

ExcludeBlockNameRegex — Exclude subsystems where block name matches regular expression pattern

string

Exclude subsystems where the block name matches a regular expression pattern, specified as a string.

Example: "^A.*"

Data Types: string

IncludeRootLevel — Include root level block diagram of model as subsystem

1 (true) (default) | 0 (false)

Include the root level block diagram of model as a subsystem, specified as a numeric or logical 1 (true) or 0 (false).

For example, for the model AHRS_Voter, the query returns the subsystems of the model and the block diagram AHRS_Voter by default.

Data Types: logical

ShowPath — Display full block path in Process Advisor

0 (false) (default) | 1 (true)

Display full block path in Process Advisor, specified as a numeric or logical 1 (true) or 0 (false).

Data Types: logical

Title — Query title

"All subsystems for a model" (default) | string | character vector

Query title, specified as a string or a character vector.

Example: "Find my subsystems"

Data Types: string

DefaultArtifactType — Default artifact type returned by query

["sl_subsystem" "sl_block_diagram"] (default) | ...

Default artifact type returned by the query, specified as one or more of the values in this table. To specify multiple values, use an array.

Category	Artifact Type	Description
MATLAB®	"m_class"	MATLAB class
	"m_file"	MATLAB file
	"m_func"	MATLAB function
	"m_method"	MATLAB class method
	"m_property"	MATLAB class property
Model Advisor	"ma_config_file"	Model Advisor configuration file
	"ma_justification_file"	Model Advisor justification file
Model Finder	"mf_database"	Model Finder database file
Process Advisor	"padv_dep_artifacts"	Related artifacts that current artifact depends on
	"padv_output_file"	Process Advisor output file
Project	"project"	Current project file
Requirements	"mwreq_file"	Requirement file (since R2024b)
	"mwreq_item"	Requirement (since R2024b)
	"sl_req"	Requirement (for R2024a and earlier)
	"sl_req_file"	Requirement file (for R2024a and earlier)
	"sl_req_table"	Requirements Table
Stateflow®	"sf_chart"	Stateflow chart
	"sf_graphical_fcn"	Stateflow graphical function
	"sf_group"	Stateflow group
	"sf_state"	Stateflow state
	"sf_state_transition_chart"	Stateflow state transition chart
	"sf_truth_table"	Stateflow truth table
Simulink®	"sl_block_diagram"	Block diagram
	"sl_data_dictionary_file"	Data dictionary file
	"sl_embedded_matlab_fcn"	MATLAB function
	"sl_block_diagram"	Block diagram
	"sl_library_file"	Library file
	"sl_model_file"	Simulink model file
	"sl_protected_model_file"	Protected Simulink model file
	"sl_subsystem"	Subsystem
	"sl_subsystem_file"	Subsystem file
System Composer™	"zc_block_diagram"	System Composer architecture
	"zc_component"	System Composer architecture component
	"zc_file"	System Composer architecture file
Tests	"harness_info_file"	Harness info file
	"sl_harness_block_diagram"	Harness block diagram
	"sl_harness_file"	Test harness file
	"sl_test_case"	Simulink Test™ case
	"sl_test_case_result"	Simulink Test case result
	"sl_test_file"	Simulink Test file
	"sl_test_iteration"	Simulink Test iteration
	"sl_test_iteration_result"	Simulink Test iteration result
	"sl_test_report_file"	Simulink Test result report
	"sl_test_result_file"	Simulink Test result file
	"sl_test_resultset"	Simulink Test result set
	"sl_test_seq"	Test Sequence
	"sl_test_suite"	Simulink Test suite
	"sl_test_suite_result"	Simulink Test suite result

Example: "sl_subsystem"

Example: ["sl_subsystem" "sl_block_diagram"]

Parent — Initial query that runs before iteration query

"padv.builtin.query.FindModels" (default) | padv.Query | Name of padv.Query object

Initial query that runs before iteration query, specified as either a padv.Query object or the Name of a padv.Query object. When you specify an iteration query for a task, the parent query is the initial query that the build system runs before running the specified iteration query.

For information on how to improve Process Advisor load times by sharing query instances across your process model, see Best Practices for Process Model Authoring.

Example: sharedQuery

Example: "FindMyInitialArtifacts"

Name — Unique identifier for query

string | character vector

Unique identifier for query, specified as a string or a character vector.

Example: "FindMySubsystems"

Data Types: char | string

ShowFileExtension — Show file extensions

0 (false) | 1 (true)

Show file extensions in the Alias property, specified as a numeric or logical 1 (true) or 0 (false). The Alias property controls the display name for the artifact in the Tasks column in Process Advisor.

By default, queries strip file extensions from the Alias property of each task iteration artifact. To show file extensions for all artifacts in the Tasks column, select the project setting Show file extensions. To keep file extensions in the results for a specific query, specify the query property ShowFileExtension as true.

Example: true

Data Types: logical

SortArtifacts — Setting for automatically sorting artifacts by address

true or 1 (default) | false or 0

Setting for automatically sorting artifacts by address, specified as a numeric or logical 1 (true) or 0 (false). When a query returns artifacts, the artifacts should be in a consistent order. By default, the build system sorts artifacts by the artifact address.

Alternatively, you can sort artifacts in a different order by overriding the internal sortArtifacts method in a subclass that defines a custom sort behavior. For an example, see Sort Artifacts in Specific Order.

The build system automatically calls the sortArtifacts method when using the process model. The sortArtifacts method expects two input arguments: a padv.Query object and a list of padv.Artifact objects returned by the run method. The sortArtifacts method should return a list of sorted padv.Artifact objects.

Example: SortArtifacts = false

Data Types: logical

FunctionHandle — Handle to function that function-based query runs

function_handle

Handle to the function that a function-based query runs, specified as a function_handle.

If you define your query functionality inside a function and you or the build system call run on the query, the query runs the function specified by the function_handle.

The built-in queries are defined inside classes and do not use the FunctionHandle.

Example: FunctionHandle = @FunctionForQuery

Data Types: function_handle

Methods

Specialized Public Methods

This class overrides the following inherited methods.

run

Run query to find the artifacts that meet the criteria specified by the query. The query returns a padv.Artifact object or an array of padv.Artifact objects that represent those artifacts. Note You do not need to manually invoke this method inside your process model. The build system automatically invokes the run method when necessary. The run method inside this built-in query runs on a query object obj and returns artifacts artifacts that are associated with the artifact iterationArtifact. If you inherit from this built-in query, make sure to use the same method signature inside your custom query: function artifacts = run(obj,iterationArtifact) ... end

Examples

Find Subsystems for Task in Process

Suppose you want your custom task to iterate over the subsystems of a specific model. You can find the subsystems by using the built-in query padv.builtin.query.FindSubsystemsForModel as the iteration query of the task.

Open a project. For this example, open the Process Advisor example project.

processAdvisorExampleStart

Edit the process model to add an example custom task that iterates over each subsystem in each model in the project. In the processmodel.m file, add this code.

    pm.addTask("MySubsystemTask",...
        IterationQuery=padv.builtin.query.FindSubsystemsForModel)

In Process Advisor, Refresh Tasks and expand the task iterations for MySubsystemTask in the Tasks column. Process Advisor shows a task iteration for each subsystem, grouped by each model in the project.

Suppose you do not want to include the subsystems associated with the model AHRS_Voter. You can filter the query results by using the query arguments. For example, you can exclude subsystems where the block path contains the text "AHRS_Voter" by using the ExcludePath argument.

    pm.addTask("MySubsystemTask",...
        IterationQuery=padv.builtin.query.FindSubsystemsForModel(...
        ExcludePath="AHRS_Voter"))

Test FindSubsystemsForModel Query Outside Process Model

Although you typically use a query inside your process model, you can run an instance of the FindSubsystemsForModel query outside of your process model to confirm which artifacts the query returns. For this example, you test a query to see which subsystems are associated with the model AHRS_Voter and then test different query filtering options.

Open a project. For this example, open the Process Advisor example project.

processAdvisorExampleStart

Create an instance of the FindSubsystemsForModel query.

q = padv.builtin.query.FindSubsystemsForModel();

Find the padv.Artifact object for the AHRS_Voter model by creating and running an instance of the FindModels query.

parentQuery = padv.builtin.query.FindModels(IncludePath="AHRS_Voter");
AHRSmodel = parentQuery.run();

Run the FindSubsystemsForModel query using AHRSmodel as the iteration artifact. The query returns the five subsystems associated with the AHRS_Voter model.

subsystems = q.run(AHRSmodel)

subsystems = 

  1×5 Artifact array with properties:

    Type
    Parent
    ArtifactAddress
    Alias

View the subsystem names by using the Alias property.

subsystems.Alias

ans = 

    "AHRS_Voter"


ans = 

    "MidValue"


ans = 

    "OneValue"


ans = 

    "ZeroValue"


ans = 

    "AvgValue"

Suppose you do not want to include the root level block diagram AHRS_Voter in the list of subsystems. You can filter out that block diagram by using the IncludeRootLevel argument of the query and re-running the query.

q.IncludeRootLevel = false;
subsystems = q.run(AHRSmodel);
subsystems.Alias

ans = 

    "MidValue"


ans = 

    "OneValue"


ans = 

    "ZeroValue"


ans = 

    "AvgValue"

Capabilities and Limitations

This table identifies functionality that is supported by the query.

Functionality	Supported?
Input query for task	Yes.
Iteration query for task	Yes.