Pause Conditions

Introduction

In a typical Twin Activate model, the number of calls to block functions can be very large during a simulation, especially when the model contains blocks with continuous-time states, due to solver calls made by numerical solver. Debugging often consists of identifying and inspecting a limited number of blocks during simulation under special circumstances. The ability to filter the calls so that the inspections can be confined to the desired blocks and circumstances is important.

The circumstances might include conditions depending on the reason for which the block is called (task to perform, such as Initialization, Output update, State update), the time, the values of inputs, or internal states. The debugger lets you define filters using predefined conditions through menus and OML expressions to express conditions to pause. Different filters can be implemented, and a call is paused only if it is not filtered out by any of the filters. The only exception to this rule is when an error is generated by a block. In that case, the pause is systematic.

Note: You can change conditions during each pause. You do not necessarily have to define all pause conditions at the start of the debugging session.

Blocks to pause

One pause condition is to make a list of blocks to pause. The List of blocks to pause is located under the action buttons in the Twin Activate debugger dialog box. To the right of the list are options to add and remove blocks. To add a specific block, select it from the Add a block to the list drop-down list.

By default, the list of blocks to pause in is empty. If the simulation is started or continued using the START or CONTINUE buttons, it either runs to the end or pauses due to an error. The behavior in this case is like that of the FINISH button. If one or more blocks are selected, then a pause cannot occur in any other block other than the selected blocks, unless an error occurs in that other block. Regardless of the chosen filters, if an error occurs during simulation in debug mode inside a block, the simulation is paused in that block.

Note: Basic blocks do not always correspond to visible blocks in the diagram since the model might contain non-inlined super blocks. For more information, see Other Paused Blocks.

The correspondence between basic blocks in the list and blocks visible in the diagram is one-to-one for most blocks. When paused, the full name of the block is shown at the top of the dialog box. To open the diagram containing the block, click Show in the upper right. The block is marked with a specific icon in the diagram indicating whether the pause is a pre-call, a post-call, or post-call subsequent to an error. These icons are shown in the image below.

Action flags

You can define pause conditions based on the block action requested by the simulator. By default, the All actions option is selected. The Simulation error or end option means that the simulation never stops unless an error occurs in a block. The other options are described in the table below.

Table 1. Block simulation flags
Flag	Action
1	Output update: Can be used in both try mode and non-try mode.
2	State updated: Updates block internal states, both continuous and discrete.
0	Derivative update
4	Initial call: Initialization actions such as opening a file. Each block is called once at the start.
6	Reinitialization call of continuous time states in try mode.
5	Final actions such as closing a file. Each block is called once at the end.
3	Event generation: Scheduling event on output activation ports.
9	Zero-crossing call: Computes the zero-crossing surfaces.

Try mode calls

You can define pause conditions based on whether to include try mode calls. By default, try mode calls are included in pause conditions. To exclude try mode calls, deselect the Include try mode calls check box in the upper right of the Twin Activate debugger dialog box.

Try mode calls are made when a variable step solver is used. The solver advances time in a try step to see if the result of taking that step meets error tolerance thresholds. If not, the solver takes a smaller step back. Try time instants and associated outputs are not considered retained values, so these calls are not typically useful for debugging. You might include try mode calls if you are an advanced user who is familiar with how the model's numerical solver works and if you are facing a numerical convergence issue.

Note: For more information on numerical solvers in general, see Extended Definitions for Advanced Users.

Phases

You can define pause conditions based on the phase of the simulation function. The pre-call phase occurs before the action of the simulation function, and the post-call phase occurs after. Including or excluding these phases lets you decide whether to pause and examine blocks before or after their actions, or both.

In the upper right of the Twin Activate debugger dialog box, select an option from the Included phases drop-down menu. You can choose both pre- and post-calls, only pre-calls, or only post-calls.

OML stopping condition

You can define pause conditions based on an OML expression. Write the OML expression in the Stopping condition field in the Twin Activate debugger dialog box. A pause occurs if the OML expression evaluates to true or 1.

The stopping condition is tested if the other conditions (block name, flag, phase, and try mode) do not filter out the call.

Note: The stopping condition might significantly slow down the simulation because the it is evaluated by the OML interpreter. The number of evaluations can be limited if used with other pause conditions.

The stopping condition can contain any of the variables in the table below. The variables that can be used are shown at the bottom of the dialog box.

Table 2. OML variables available for stopping condition
Variable	Description
`block_name`	Block name (string)
`t`	Current simulation time (double)
`inputs`	Input values (cell \| mat)
`outputs`	Output values (cell \| mat)
`nevprt`	Block activation code (double)
`x`	Continuous-time state (vector)
`xd`	Derivative of the continuous-time state (vector)
`mode`	Block modes (vector)
`zcross`	Zero-crossing surfaces (vector)
`z`	Discrete-time block state (vector)
`oz`	Discrete-time object states (cell \| mat)
`rpar`	Block parameter (vector)
`opar`	Object parameters (cell \| mat \| scalar \| string)
`trymode`	True if call is made in try mode, otherwise false
`block`	OML object corresponding to the block structure
`flag`	Indicates the action associated with the call
`prepost`	0 or 1 depending whether in pre- or post-call phase

A simple example of an OML stopping condition is to only accept pauses after time has passed 0.05:

t > 0.05

The following expression pauses only if the input of the selected block is negative:

inputs{1} < 0

The following expression pauses only for negative inputs after time passes 1:

t > 1 && inputs{1} < 0