Model debugging in Engee

Debugging plays a key role in model development, allowing us to check whether the operation of individual parts of the model and its behaviour meet our expectations. This process helps to identify and eliminate errors, to check that the data is transferred correctly and that the dimensions match the intended ones. If the output of the model is incorrect, debugging allows us to understand where and how the behaviour of the system deviates from what we expect.

This article describes the main approaches to debugging models using Engee tools.

Initial debugging of models

At the initial stage of model development it is important to make sure that its components and connections (signal lines) work correctly. Initial debugging allows you to identify basic errors such as incorrect block parameters, incorrect input data, or incorrect execution logic.

Signal graphs

The easiest way to check is mark signals for recording signal logging 1 and observe on the charts where the model starts to behave incorrectly (for more details see the article Graphs).

Disabling and skipping blocks

In the process of debugging models it is often necessary to temporarily exclude some blocks from execution, which is analogous to code commenting in textual programming languages.

To disable/skip a block, right-click on it and select the necessary option in the context menu:

Disable block - the block is completely excluded from the model as if it did not exist. Its inputs and outputs are disconnected and it does not participate in the modelling process in any way. This allows you to test how the model will work without this block. Consequently, if a block is disconnected, no signal is passed through it and the components associated with its outputs do not receive data.
Skip block - the block remains in the model, but its functionality is ignored. The inputs of the block are directly connected to its outputs and the data passes through unchanged. This is equivalent to connecting all block inputs to their corresponding outputs.

Passing is not available for some blocks.

Properties tab of the settings window

settings first

Selecting the simulation mode

Parameters Mode parameter allows you to customise simulation execution depending on debugging tasks and performance. For debugging, the mode is particularly useful for minimising start-up time and simplifying model handling. A total of two modes are available:

Fast initialization - The model runs as fast as possible due to simplified typing and disabling optimisations. This mode is convenient for debugging, as it allows you to quickly check changes in the model without waiting for a long launch. It is especially useful for frequent changes of model structure or parameters.
Fast simulation - Priority is given to high performance and reduced computation time. Although this mode is less flexible for debugging, it can be useful at the final stages of verification, when it is necessary to make sure that the calculations are correct and stable.

Therefore, at the initial stages it is recommended to use the mode Fast initialization*to quickly find and eliminate errors, and at the final stages - to check the model performance. *Fast simulation to check the model performance.

Simulation speed control

Parameters Enable pacing to slow down simulation allows you to set the ratio of simulation time to real time, specifying how many simulation seconds should pass in one real second.

The setting is useful for debugging, as slowing down the simulation helps to better analyse the behaviour of the model in real time. It allows you to:

Clearly track signal changes on graphs;
Conveniently work with animations to check model execution step-by-step.

Consequently, slowing down the simulation creates a controlled working environment in which you can interact with the model, analyse signal behaviour and troubleshoot problems in the early stages of debugging.

Tab "Debugging" of the settings window

Displaying information

When debugging models, it is important to be able to visually track key features to understand how data is transferred and processed in blocks. Different types of information can be displayed in Engee:

information display 1

Data types - displays the data types of the signal lines between the model blocks. If an incorrect data type is present in the model, when the function is selected, [diagnostic window] will automatically appear with an error message. Data types diagnostic window will automatically appear with the error.

*Data type display example
Line dimensions - displays dimensions of signal lines between model blocks (see Working with signals of different dimensions). Model signals can be scalar, vector and matrix.
Examples of mapping with different signals
- Scalar signal is a single data value that has no direction and is the simplest type of signal:
- Vector signal - an ordered set of data of the same type, organised as a vector, which has a direction and may contain several elements.
- Matrix signal - a two-dimensional data array consisting of rows and columns, and can contain data of different types. A matrix can be used to represent multiple signals simultaneously.
Signal sampling rate - displays the sampling rate of the model blocks. A small sampling step may result in a larger amount of data, which may slow down the simulation. Too large step can lead to loss of accuracy of model calculation. It is convenient to use the block Rate Transition to control the sampling rate of the signal.

Sampling frequency example

Here for the DSP Sine Wave block the amplitude 1, frequency 2 Hz and sampling step equal to 0.001 for the first channel (D1, DSP Sine Wave block) and 0.01 for the second (D2, DSP Sine Wave-1 block) are set. In the Rate Transition block the sampling step is set: 0.005 for D1 and 0.02 for D2. This will allow you to see on the graph: D1 signal is smoothed and accurate, D2 signal is stepped, with less detail.
- Highlighting - option sub-item Signal sampling rate allows you to highlight one of the following options: signals with the current sampling rate, signal source, or do not highlight anything (selected by default). Discrete signals can be displayed in different colours depending on the sampling rate of the signal (as in the example above).
Blocks execution sequence - allows you to know the order of execution of blocks in the model. The sequence of model execution will be displayed by numbers, where 1 is the first executable block in the model. This option helps to control the sequence of block execution to avoid unwanted dependencies and improves the readability of the model.

*Example of execution order

Recording of signals

Signal recording allows you to record simulation results and analyse them for further diagnostics and debugging. In Engee there are two ways to record signals:

signal recording 1

Save simulation results to workspace - allows you to save the results of the model simulation to the working area (variable window ) as a simout variable. This allows you to access the data after the simulation is finished and use it for analysis, visualisation or further processing. For more information about saving simulation results, see the article Software processing of simulation results in Engee.
- Physical Variables - allows you to write data from selected blocks. Only blocks from the library are suitable for writing Physical Modeling. Right-click on the block whose signal you want to record and select the option Log Physical Signals option in the context menu:
  
  The recorded variables are displayed in the module Plots and in the application Data Inspector.
  
  *Examples of recorded signals
  
  Recorded variables in the module Plots:
  
  Recorded variables in the application Data inspector:
Results of physical variables initialization - displays the values of physical variables in the physical variables window .

Real-time debugging

The Engee environment allows you to monitor model execution in real time. This approach combines several tools that help to monitor step by step the state of signals, blocks and their dynamic processes:

interactive debugging 1

Enable stepping back - allows you to run the model one time step at a time. Enabling the setting adds additional buttons to the top Engee modelling menu:

This mode allows you to customise parameters:
- Maximum number of saved back steps - parameter determines how many simulation steps will be stored in memory. Useful for understanding how the model reached the current state and for debugging, as it allows you to compare the changes at each step.
- Interval between stored back steps - parameter sets how many time steps the model state will be stored in memory.
- Move back/forward by - parameter defines the number of steps the model will advance:
  - Step forward - the simulation continues for the specified number of steps. For example, if the value of the parameters "Step forward/backward by" is 2, the simulation will advance by two steps.
  - Step back - the simulation goes back the specified number of steps. Engee restores the working point of the model state, from which the selected number of steps is returned.
Showing current signal value - allows marking signals to display the instantaneous value during simulation or step-by-step execution. This method is visual and convenient for visually analysing the data transfer between blocks.

Animation speed - controls the speed of finite automaton (supported inside the block Chart). It has four modes: off (by default), slow, medium and fast.

Breakpoints

One of the most important tools for debugging models is breakpoints. They allow you to pause the execution of the model at the right moment in the simulation to examine the state of the system, to find errors or to check the operation of individual blocks and settings.

To open the breakpoint editor, go to the settings window and in the tab Debugging select Open the breakpoint list:

breakpoints adding 1

This will open the editor to work with breakpoints:

breakpoints 1

Consider an example where breakpoints are used to stop the simulation at a particular stage. To do this, assemble the model from blocks Sine Wave Function and Terminator, switch on signal recording:

sine wave terminator model

With the left mouse button, select the signal line and in the breakpoint editor click breakpoint add . In the window that opens, select less than zero as shown in the figure: