Diff Tool

The Diff tool can be used to compare two PLECS models or two subsystems of PLECS models. The result of a Diff is a side-by-side comparison of the two models showing all the differences between them. Depending on the kind of change, a suitable view is used, e.g. a schematic to show inserted or deleted components or a parameter dialog to show changed parameter values. The Diff browser can be used to navigate through the differences. A “relevance” value for each difference helps you to identify the most important changes.

This chapter is divided into four sections. The first section describes how to select two models or subsystems and compute a Diff for them. The second section gives an overview on how the result of the Diff is presented to the user. The third section explains the algorithms PLECS uses to compute the Diff. Finally, the fourth section lists the limitations of the Diff tool.

How to Compute a Diff

Computing a Diff in PLECS Standalone

The Diff tool can compare either two complete PLECS models or two subsystems contained in one or two PLECS models. To compute a Diff, choose the option Compare in the File menu. This opens the Diff dialog.

../_images/diff_dialog_standalone.png

Fig. 123 Standalone Diff dialog

This dialog has the two rows “Before” and “After” to specify the two entities that should be compared. You can use drag&drop to specify a model or a subsystem for comparison. Each row in the Diff dialog contains the following fields:

Model file

This field is used to specify the path of the model file. Depending on the models that are currently open in PLECS, this field is already filled with a reasonable suggestion. You can also use drag&drop or the Open file browser button (…) to choose a file.

Subsystem path

This field can be used to specify a subsystem for the comparison. If you want to compare subsystems you have to specify a subsystem for both the “before” and “after” row. You cannot compare a model with a subsystem. The subsystem path should also contain the name of the model, which can be abbreviated by a dot (.). If you use only the model name or a dot or if you leave this field empty, the whole model will be compared. Depending on the subsystems that are currently selected in PLECS, this field is already filled with a reasonable suggestion. You can also drag&drop a subsystem from a schematic window.

State

This is a drop-down list that can specify either one of the values File state or Editor state. If you choose File state, the state the model has in the model file is used for comparison. If you choose Editor state, the unsaved changes of an open model are used for comparison. This can be useful to review changes before saving a model.

Differences are defined as editing steps from the “before” model to the “after” model. A component present in the “before” model but missing in the “after” model will be displayed as a deletion. If you decide that you would like the differences to be presented the other way around, use the Swap button to swap all fields in the “before” and “after” row.

Once you have filled out all fields, press the Compare button to start the Diff computation. A progress bar will show the current state of the Diff computation. If you want to abort the Diff computation, press Cancel. Once the Diff computation has finished, the Diff result window will show the result.

Command Line Interface

PLECS Standalone can be used as an external diff viewer in version control systems such as Git. To compare two files, use the following command line syntax:

plecs -diff leftModelFile rightModelFile

or on macOS:

PLECS.app/Contents/MacOS/PLECS -diff leftModelFile rightModelFile

Computing a Diff in PLECS Blockset

The Diff tool can compare either two complete PLECS circuits contained in one or two Simulink models or two subsystems contained in one or two PLECS circuits. To compute a Diff, choose the option Compare in the File menu. This opens the Diff dialog.

../_images/diff_dialog_blockset.png

Fig. 124 Blockset Diff dialog

This dialog has the two rows “Before” and “After” to specify the two entities that should be compared. You can use drag&drop to specify a model or a subsystem for comparison. Each row in the Diff dialog contains the following fields:

Model file

This field is used to specify the path of the Simulink model file. Depending on the models that are currently open, this field is already filled with a reasonable suggestion. You can also use drag&drop or the Open file browser button (…) to choose a file. Valid model file extensions are mdl and slx.

Circuit path

This field is used to specify the path of the PLECS Circuit within the Simulink model. It should start with the Simulink model name and end with the PLECS Circuit name. Depending on the models that are currently open, this field is already filled with a reasonable suggestion.

Subsystem path

This field can be used to specify a subsystem for the comparison. If you want to compare subsystems you have to specify a subsystem for both the “before” and “after” row. You cannot compare a circuit with a subsystem. The subsystem path should also contain the name of the circuit, which can be abbreviated by a dot (.). If you use only the circuit name or a dot or if you leave this field empty, the whole circuit will be compared. Depending on the subsystems that are currently selected in PLECS, this field is already filled with a reasonable suggestion. You can also drag&drop a subsystem from a schematic window.

State

This is a drop-down list that can specify either one of the values File state or Editor state. If you choose File state, the state the circuit has in the model file is used for comparison. If you choose Editor state, the unsaved changes of an open model are used for comparison. This can be useful to review changes before saving a model.

Differences are defined as editing steps from the “before” model to the “after” model. A component present in the “before” circuit but missing in the “after” circuit will be displayed as a deletion. If you decide that you would like the differences to be presented the other way around, use the Swap button to swap all fields in the “before” and “after” row.

Once you have filled out all fields, press the Compare button to start the Diff computation. A progress bar will show the current state of the Diff computation. If you want to abort the Diff computation, press Cancel. Once the Diff computation has finished, the Diff result window will show the result.

How to Interpret the Results

The result of computing a Diff is shown in the Diff result window. This window contains a Diff browser and two views, one for the “before” model and one for the “after” model.

../_images/diff_result_window.png

Fig. 125 Diff result window

The Diff Browser

The Diff browser can be used to navigate through the differences between the two models. It is similar to the Circuit Browser shown in schematic windows (see Circuit Browser). However, there are three important differences:

  1. The Diff browser shows not only components but also all other kinds of items stored in a model, e.g. parameters, properties like the positions of components, analyses and simulation scripts

  2. The Diff browser only shows the items that actually changed

  3. The Diff browser merges both models into one tree, i.e. an item in the tree represents the corresponding item in both models (if it exists)

There are cases where an item is located in different schematics in the “before” and “after” models. For example, if a resistor is in the root schematic in the “before” model and within a subsystem in the “after” model, it will appear twice in the Diff browser.

The Diff browser shows the three columns Name, Type and Relevance.

Name

This column shows the name of the corresponding item. The hierarchical structure of the model is shown as a tree. Use the little arrows to navigate into nested items. The colored icons next to the item names illustrate the kind of change:

  • A red icon delete means that the corresponding item was deleted from the “before” model

  • A green icon insert means that the corresponding item was inserted into the “after” model

  • A blue icon modify means that the corresponding item was modified

For renamed items, both the “before” and “after” names are shown, with an arrow (→) between them.

Type

This column shows the type of the corresponding item. The type is also illustrated by the icon. There are the following types:

  • circuit PLECS Circuit

  • subsystem Subsystem

  • component Component (other than a Subsystem)

  • connection Connection

  • annotation Annotation

  • terminal Terminal

  • parameter Parameter

  • setting Setting

  • assertion Component assertion

  • scope_plot Scope plot

  • xy_plot XY-plot axis

  • fourier_plot Fourier plot

  • probe Probe (entry for a component in a Probe block or a mask probe)

  • mask_probe Mask probe (entry in the list of probes for a masked subsystem)

  • simulink_probe Simulink probe (entry in a Simulink Probe block)

  • netlist_probe Netlist probe (entry in a PLECS Spice Netlist block)

  • fsm_state State machine state (includes entry points and junctions)

  • fsm_transition State machine transition

  • fsm_annotation State machine annotation

  • fsm_parameter State machine parameter

  • analysis Analysis

  • simulation_script Simulation script

  • property Property (of an item of any type)

This list is exhaustive, i.e. every data item in a model has one of the above types.

Note

The item types in the Type column of the Diff browser are distinct from the component types shown in the Type column of the Circuit browser.

Relevance

This column shows a “relevance” for each item shown in the Diff browser. The relevance gives an estimation for the importance of a change. It can have the following values:

Simulation

The difference may have an impact on the result of a simulation. Example: changing a component parameter value.

Representation

The difference does not influence the simulation, but how a model is displayed in the GUI. Example: changing the position of a component in the schematic.

Model file

The difference does not influence the simulation and is not directly visible in the GUI either, but it is visible in the model file. Example: changing the PLECS version in which the model is saved.

Tool Buttons

The Diff browser also shows the following tool buttons:

Previous View  nav_180

Use this button to return to the previous item that was shown in the views.

Next View  navigation

Use this button to go to the next item in the list of visited items.

Filter Options  filter

Use this button to filter items according to their relevance (see Relevance).

Refresh  refresh

Use this button to recompute the Diff after one of the compared original models changed.

The Diff Views

To the right of the Diff browser, there are two views that show the currently selected item in the appropriate context, e.g., a changed component is shown in the parent schematic, a changed parameter is shown in the parameter dialog. Each view shows the path of the currently visible item at the top. By clicking on an element of the path, you can navigate to the corresponding item.

By default, the left view shows the “before” model and the right view shows the “after” model. You can swap the two views in the General tab of the PLECS preferences dialog (see Configuring PLECS). Note that swapping the views only changes their location in the window and has no influence on the roles of the “before” and “after” models.

As in the Diff browser, items deleted from the “before” model are marked in red, items inserted into the “after” model are marked in green and modified items are marked in blue. A spotlight is used to facilitate finding the changed item.

You can navigate through the models as in a normal Schematic window. However, editing is disabled, because the Diff result is only valid for the particular state the models were in when you pressed the Compare button.

How Diff Works

Classical Diff algorithms (like Miller & Myers, 1985) operate on linear lists. This works well for continuous text but cannot account for the hierarchical structure of tree-like data. A PLECS model is a collection of nested linear and hierarchical data. To compute a useful Diff between two PLECS models, we therefore employ an algorithm that uses a linear Diff algorithm (Miller & Myers, 1985) for linear structures and a hierarchical Diff algorithm (Zhang & Shasha, 1989 and Paassen, 2018) for hierarchical structures and applies them recursively to nested data as appropriate. For example, the hierarchical algorithm is used to compare the trees of subsystems and components, and within a C-Script block, the linear algorithm is used to compare each C code snippet.

The result of the algorithm is a mapping of items in the “before” model to items in the “after” model. Items that are mapped to each other are considered to be “the same” item. Items that are in the mapping and identical are reported to be unchanged. Items that are in the mapping and not identical are reported to be modified. Items that are not in the mapping but present in the “before” model are reported to be deleted. Items that are not in the mapping but present in the “after” model are reported to be inserted.

References

  • W. Miller and E. W. Myers, “A file comparison program”, Softw: Pract. Exper., 15: 1025-1040, 1985, https://doi.org/10.1002/spe.4380151102

  • K. Zhang and D. Shasha, “Simple Fast Algorithms for the Editing Distance between Trees and Related Problems”, SIAM Journal of Computing, 18(6): 1245-1262, 1989

  • B. Paassen, “Revisiting the tree edit distance and its backtracing: A tutorial”, 2018, https://arxiv.org/abs/1805.06869

Limitations

Model Conversion

PLECS computes Diffs based on the internal representation of a model rather than the text contents of a model file. If a model is not open yet, it will be loaded into the internal representation before the comparison. If the model file was saved with a different version of PLECS, this internal representation may differ from the model file due to differences between the PLECS versions. This means that the Diff shown in PLECS may not contain certain differences that are present in the model files. PLECS shows a warning if the versions of the compared models do not match.

Non-Intuitive Results

The result shown in the Diff result window may sometimes not correspond to what you would consider the “correct” result. There are mainly two reasons for this:

  1. While there are many ways to edit a model, the Diff algorithm (see How Diff Works) detects only three distinct edit operations: deletions, insertions and modifications. Also, the order of the items and their parent-child relationships within the models must be preserved in order for an item to be considered the same item in the “before” and “after” models.

  2. The ordering of the items in the model is not directly visible in the GUI. This corresponds to the order in which the items are stored in the model file and has nothing to do with the coordinates of a component within a schematic.

An example of a non-intuitive result may be the following: Consider a model containing only a resistor and a diode in the root schematic, in this order. Now the user adds a subsystem and moves the diode into it. As expected, the Diff result will be an inserted subsystem in the “after” model and a modified diode, located in the root schematic in the “before” model and within the subsystem in the “after” model. However, if the user, instead of moving the diode into the subsystem, moves the resistor into the subsystem, the Diff result will be a deleted resistor in the “before” model and an inserted subsystem and inserted nested resistor in the “after” model.

The reason for the second, unexpected result is that inserting a subsystem and moving the resistor into it changes the order of the components. Because the subsystem is added at the end of the list of components in the schematic, and the resistor is removed from the beginning of the same list, moving the resistor into the subsystem changes its position relative to the diode. The resistor can therefore not be part of the mapping and is detected as deleted and inserted instead of just modified.

Though situations like the one described above exist, the result that the Diff algorithm produces is always correct in the sense that it represents a minimal valid sequence of deletions, insertions and modifications that lead from the “before” model to the “after” model.