Main Content

assert

Program customized run-time errors and warnings

Syntax

assert (predicate_condition, message, Action);

Description

The equations section may contain the assert construct, which lets you specify customized run-time errors and warnings:

assert (predicate_condition, message, Action);

predicate_conditionThe expression to be evaluated at run time. It can be a function of time, inputs, parameters, and variables.
messageOptional text string (with single quotes) that tells the block user why the run-time error or warning is triggered.
ActionOptional attribute that specifies whether triggering the assert results in a warning or an error during simulation. The default action is error.

The Action attribute lets you specify the assert action based on an enumerated parameter value. A built-in enumeration simscape.enum.assert.action allows three possible actions when the assertion is triggered: error, warn, and none. You can provide an enumerated value directly to the Action attribute:

assert(u > 0, Action = simscape.enum.assert.action.warn)

or create an enumerated parameter and let the block user control the assert action:

parameters
  assert_action = simscape.enum.assert.action.warn 
end

equations
  assert(u > 0, Action = assert_action)
end

You can use the assert construct in:

  • The top-level equations, including initial equations.

  • The if-elseif-else branches of a conditional expression.

  • The expression clause and the right-hand side of the declaration clause of a let expression.

When you use an assert construct in a branch of a conditional expression, it is not counted towards the number of expressions in the branch, and is therefore exempt from the general rule that the total number of equation expressions, their dimensionality, and their order must be the same for every branch of the if-elseif-else statement. For example, the following is valid:

if x>1
     y == 1;
else
     assert(b > 0);
     y == 3;
end

The scope of the assert construct is defined by the scope of its branch. In the preceding example, the predicate condition b > 0 is evaluated only when the else branch is in effect, that is, when x is less than or equal to 1.

When you include assert constructs in initial equations, their predicate conditions are checked only once, after solving for initial conditions (before the start of simulation, see Initial Conditions Computation). Use these assertions to safeguard against the model initializing with nonphysical values.

Examples

Run-Time Error

Generate a run-time error if the fluid volume in a reservoir becomes negative: 

assert( V >= 0, 'Insufficient fluid volume for proper operation' );

During simulation, if the internal variable V (corresponding to the volume of fluid in the reservoir) assumes a negative value, simulation stops and outputs an error message containing the following information:

  • Simulation time when the assertion got triggered

  • The message string (in this example, Insufficient fluid volume for proper operation)

  • An active link to the block that triggered the assertion. Click the Block path link to highlight the block in the model diagram.

  • An active link to the assert location in the component source file. Click the Assert location link to open the Simscape™ source file of the component, with the cursor at the start of violated predicate condition. For Simscape protected files, the Assert location information is omitted from the error message.

Run-Time Warning

If you do not want simulation to stop, but still want to display a warning that a certain condition has been violated, set the Action attribute to simscape.enum.assert.action.warn. For example, if hydraulic pressure drops below fluid vapor saturation level at some point, this condition may result in cavitation and invalidate the modeling assumptions used in a block. You can add the following assert construct to the hydraulic component equations:

assert( p > p_cav, 'Pressure is below vapor level; cavitation possible', 
                              Action = simscape.enum.assert.action.warn);

In this case, if the predicate condition is violated, the simulation continues, but outputs a warning message. The format of the warning message is the same as of the error message described in the previous example.

The warning message appears once, at the first time step when the predicate condition is violated. In this example, the warning message appears at the first time step when the pressure drops below vapor level. As long as the pressure stays below that level, the message is not repeated at subsequent time steps. However, as the simulation continues, if the pressure raises above the vapor saturation level and then again drops below that level, the assertion gets reactivated and the warning message appears once again.

User-Controllable Action

If you want to let the block user control the action upon triggering the assert, create an enumerated parameter and set the Action attribute to be based on the value of this parameter.

For example, in a Stepper Motor block, you can let the block user decide upon the desired action when the motor slips. Declare a control parameter, based on the built-in assert action enumeration, and add the following assert construct to the component equations:

parameters
  assert_action = simscape.enum.assert.action.warn % Action on slipping
end

equations
  assert(slipping<1,'Stepper motor slip',Action = assert_action)
end

In this case, the default action is also a run-time warning, like in the previous example. However, the block dialog contains an enumerated parameter, Action on slipping, with three possible values: error, warn, none. This parameter lets the block user decide whether the simulation should stop with an error, continue with a warning, or ignore the motor slips completely.

Version History

Introduced in R2011b

expand all

See Also

Topics