mcscert / model-comparison-utility

Matlab command-line functions for supporting Simulink model comparison

Model Comparison Utility

The Model Comparison Utility provides command line functions for supporting Simulink model comparison.

Differencing between two models is natively supported in Simulink via the Simulink Comparison Tool. This tool can generate a Word or HTML report displaying the changes that occur between models. Unfortunately, for large industrial models, these generated reports are not readable. As an alternative, the tool can output the comparison results to the Matlab base workspace as an EditsObj object that is structured as a tree.

Unfortunately, MathWorks provides no built-in commands to be able to easily and programmatically query or parse this tree from the command line or a script. Manually doing so for industrial models is simply not possible. Moreover, extracting information from the tree requires thorough knowledge of the tree structure and the object parameters, and thus is not trivial without much effort. The Model Comparison Utility was created to facilitate such operations via a collection of commands. Some useful commands provided by this tool are:

• find_node - Search the comparison tree for nodes with specific block types, changes, names, etc.
• getHandle - Get the handle of the model element associated with the node from the comparison tree.
• getPath - Get the pathname of the model element associated with the node from the comparison tree.
• getNodeType - Determine whether the node presents a block, line, annotation, mask, etc.
• plotTree - Plot the digraph of the comparison tree.
• treeToTable - Convert the comparison tree to a table.
• summaryOfChanges - Print a summary report of the changes in the comparison tree to the Command Window or a .txt file.

Many other commands are included and are free to be used, but are not listed here. Please explore the source files for this utility to see all the of the various functions.

User Guide

For installation and other information, please see the User Guide.

model-comparison-utility's Issues

Annotations are not detected

Given an annotation that exists in the model, that does not pass the isAnnotation test in getNodeType.m, it is still possible to determine that it is an annotation by looking at the model. However, getPath does not return the annotation path, so currently they are listed as "unknown" node types, even though it is possible to determine their type in this case. The function getPath needs to be modified to get the path and confirm that it is an annotation. The caveat is that the comparison tree annotation nodes truncate the annotation text and use it as the name of the node. So the assembled path of the node does not quite match the real path of the annotation as it is in the model.

Tree plot node names are too long

Currently, the nodes are named with their full pathname, so that they remain unique. This avoids issues when there are several blocks with the same name (e.g. "Subsystem", "In1"). However, this makes the graph less readable. We need to find a way to give the nodes labels that only consist of their name.

Incorrect node labels

For simple graphs, the root node labels are incorrect.

getStateflowType.m is no found

Support Stateflow

Currently, there is no support for recognizing Stateflow elements such as charts, transitions, junctions, states, truth tables, MATLAB functions, and variables defined in a chart. Several changes are needed to the tool to add support.

Functionality

Functions need to be updated to provide meaningful output for Stateflow elements, for example:

• src/getPath, src/getHandle should use the Stateflow API to search for the element in the model.
  Items internal to Stateflow blocks (Charts, Truth Tables, Transition Tables) do not have valid paths. You can construct paths for these items, but they will not work with get_param and similar commands. You need to use the Stateflow API to access these elements instead. As a result the getPath and getHandle functions will return the path/handle for the Stateflow block.
• src/type/nodetype/isStateflow (or some equivalent) should be created to support identification of a Stateflow elements without the need to query the model (if possible)
• src/type/nodetype/getNodeType should use these new function(s) to identify Stateflow elements. Currently it outputs 'unknown'.
• src/find_node should support the use of the Stateflow categories as the NodeType argument.

Testing

Other scripts should be tested to ensure they work with Stateflow, such as:

• src/type/changetype/getNodeChangeType: Stateflow elements should still register as being added/deleted/renamed/modified.
• src/plot/plotTree: Stateflow elements should be plotted as nodes with correct names and appropriate connecting edges.
• src/highlight/highlightNodes: Stateflow elements should be highlighted in the model (if supported by MathWorks).
  Highlighting multiple Stateflow objects inside a chart is currently not supported. The function will try to highlight all Stateflow objects successively, however, additional highlighting clears the previous object, so ultimately only the last one will appear.

Documentation

• The tool documentation should be updated to indicate support for Stateflow. If there are any major nuances with supporting Stateflow, perhaps a separate small demo example is needed.

plotTree(Edits) broken

Plotting the example with demo_before.mdl and demo_after.mdl is currently broken (Matlab R2021b). My fix: change getNodeType.m line 51 to elseif ~isempty(node.Parameters) && any(strcmp({node.Parameters.Name}, 'BlockType')) || isBlock(node)

I don't know why the (cumbersome) expression ~isempty(node.Parameters) && any(strcmp({node.Parameters.Name}, 'BlockType')) was used, so maybe my fix breaks something else.