Program customized run-time errors and warnings
equations section may contain the
which lets you specify customized run-time errors and warnings:
|The expression to be evaluated at run time. It can be a function of time, inputs, parameters, and variables.|
|Optional text string (with single quotes) that tells the block user why the run-time error or warning is triggered.|
|Optional attribute that specifies whether triggering the assert results in a warning or an error during simulation. The default action is error.|
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:
none. You can provide an enumerated value directly to the
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.
if-elseif-elsebranches of a conditional expression.
The expression clause and the right-hand side of the declaration clause of a
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
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
b > 0 is evaluated only when the
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.
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
messagestring (in this example,
Insufficient fluid volume for proper operation)
An active link to the block that triggered the assertion. Click the
Block pathlink to highlight the block in the model diagram.
An active link to the assert location in the component source file. Click the
Assert locationlink 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 locationinformation is omitted from the error message.
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.
If you want to let the block user control the action upon triggering the
assert, create an enumerated parameter and set the
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:
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 HistoryIntroduced in R2011b
R2019a: Assert Action Attribute
Prior to R2019a, you specified the assert action by using the
true|false attribute. This attribute still works. Currently,
there are no plans to remove it.
Internally, the old attribute values are automatically mapped to the
appropriate values of the new
|Old Syntax||New Syntax|
You cannot use the
attributes together in a single
construct. When authoring new components, use the
attribute because it provides more flexibility.