Main Content

padv.builtin.query.FindUnits Class

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

Query for finding units

expand all in page

Description

This class requires CI/CD Automation for Simulink Check.

The padv.builtin.query.FindUnits class provides a query that can return the units in your project. The query uses the same unit classification as the Model Design and Model Testing Dashboards. A unit is a functional entity in your software architecture that you can execute and test independently or as part of larger system tests. Some software development standards, like certain testing objectives, apply specifically to units in a software architecture. You can use the FindUnits query to find the Simulink® and System Composer™ models in your design that you need to assess. If you need to find both the units and components in your design, you can use the built-in query padv.builtin.query.FindDesignModels instead. For information how to classify the models in your project, see Categorize Models in Hierarchy as Components or Units.

You can use this query in your process model to find the units in your project and run tasks on those artifacts. For example, you can reconfigure the built-in task padv.builtin.task.CollectMetrics to collect model and code testing metrics for the units in your project by specifying the task iteration query as padv.builtin.query.FindUnits.

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

Creation

Description

query = padv.builtin.query.FindUnits creates a query for finding the units in your project.

example

query = padv.builtin.query.FindUnits(Name=Value) sets certain properties using one or more name-value arguments. For example, query = padv.builtin.query.FindUnits(ExcludePath = "Control") creates a query that finds the units in the project, but excludes units that have "Control" in the file address.

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

Input Arguments

expand all

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: query = padv.builtin.query.FindUnits(ExcludePath = "Control")

Exclude artifacts with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

Example: {"Classification","Design"}

Data Types: cell

Exclude artifacts where the path contains specific text, specified as a string or a character vector.

Example: "Control"

Data Types: char | string

Find artifacts with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

Example: {"Classification","Design"}

Data Types: cell

Find artifacts where the path contains specific text, specified as a string or a character vector.

Example: "Control"

Data Types: char | string

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

Example: "FindUnits"

Data Types: char | string

Properties

expand all

Find artifacts with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

Example: {"Classification","Design"}

Data Types: cell

Exclude artifacts with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

Example: {"Classification","Design"}

Data Types: cell

Find artifacts where the path contains specific text, specified as a string or a character vector.

Example: "Control"

Data Types: char | string

Exclude artifacts where the path contains specific text, specified as a string or a character vector.

Example: "Control"

Data Types: char | string

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

Example: "Units"

Data Types: char | string

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.

CategoryArtifact TypeDescription

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

Other

"coder_code_files"Code files
"other_file"Other 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_item"Requirement (since R2024b)

"sl_req"

Requirement (for R2024a and earlier)
"sl_req_file"Requirement file
"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
"sl_subsystem"Subsystem

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: "zc_file"

Example: ["sl_model_file" "zc_file"]

Query that the build system can run first, specified as either a padv.Query object or the Name of a padv.Query object.

If you use padv.builtin.query.FindUnits as an iteration query in your process model, the build system automatically runs the Parent query first. If there is an existing query that you want the build system to run first, specify that query as the Parent query. For example, the built-in query FindModelsWithTestCases specifies FindModels as a Parent query.

If you use padv.builtin.query.FindUnits as an input query or dependency query for a task, the build system ignores the Parent query.

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

Example: "FindUnits"

Data Types: char | string

Show file extensions in the Alias property of returned artifacts, 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

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

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

expand all

Examples

collapse all

You can use the FindUnits query in your process model to find units and components that your tasks can iterate over (IterationQuery) or use as inputs (InputQueries). For example, suppose you have a custom task that you want to run for each unit in your project. You can find the units in your project by using the built-in query FindUnits.

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

processAdvisorExampleStart

To have the custom task run for each unit, specify the FindUnits query as the iteration query for the task. For example, in your process model:

pm.addTask("MyCustomTask",...
    IterationQuery = padv.builtin.query.FindUnits);

In Process Advisor, view the updated Tasks by clicking Refresh Tasks and switching to the Project view. For the task MyCustomTask, there is one task iteration for each unit in the project. The Process Advisor example project four units: AHRS_Voter, Actuator_Control, InnerLoop_Control, and OuterLoop_Control.

To view how the example project is classifying units and components, open the options for the Model Testing Dashboard.

modelTestingDashboard
In the dashboard toolstrip, click Options. The Classification section shows that the digital thread classifies models with the project label Software Component as components and models with the project label Software Unit as units.

For information how to classify the models in your project, see Categorize Models in Hierarchy as Components or Units.

If you want to test a query before using the query in your process model, you can run the query directly from the MATLAB Command Window.

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

processAdvisorExampleStart

In the MATLAB Command Window, create a query object that represents the query.

q = padv.builtin.query.FindUnits;

Run the query by using the run method. The query returns the artifacts that it finds as a padv.Artifact object or an array of padv.Artifact objects.

artifacts = q.run
artifacts = 

  1×4 Artifact array with properties:

    Type
    Parent
    ArtifactAddress
    Alias

You can inspect the properties of each padv.Artifact object to view information about the artifact. For example, you can use the Alias property to view the artifact names.

artifacts.Alias
ans = 

    "OuterLoop_Control.slx"


ans = 

    "AHRS_Voter.slx"


ans = 

    "Actuator_Control.slx"


ans = 

    "InnerLoop_Control.slx"
The Alias property returns the artifact names as they appear in Process Advisor.

Capabilities and Limitations

This table identifies functionality that is supported by the query.

FunctionalitySupported?

Input query for task

Yes. See InputQueries.

Iteration query for task

Yes. See IterationQuery.

Note

If you use this query as an input query and specify non-empty values for IncludeLabel, ExcludeLabel, IncludePath, or ExcludePath, your task results can unexpectedly become outdated. If you see this behavior, consider using a different query, like padv.builtin.query.FindArtifacts, instead. For more information and a list of queries that are not impacted by this limitation, see Other Limitations.

See Also

| |

Topics