This information is part of the Modelica Standard Library maintained by the Modelica Association.

Activate equations or statements when condition becomes true

Examples

 equation
   when x > 2 then
     y3 = 2*x +y1+y2; // Order of y1 and y3 equations does not matter
     y1 = sin(x);
   end when;
   y2 = sin(y1);

Syntax

In equation sections:

  when expression then
    { equation ";" }
  { elsewhen expression then
    { equation ";" } }
  end when

In algorithm sections:

  when expression then
    { algorithm ";" }
  { elsewhen expression then
    { algorithm ";" } }
  end when

Description

The expression of a when clause shall be a discrete-time Boolean scalar or vector expression. The equations and algorithm statements within a when clause are activated when the scalar or any one of the elements of the vector expression becomes true. When-clauses in equation sections are allowed, provided the equations within the when-clause have one of the following forms:

• v = expr;
• (out1, out2, out3, ...) = function_call(in1, in2, ...);
• operators assert(), terminate(), reinit()
• For and if-clause if the equations within the for and if-clauses satisfy these requirements.
• In an equation section, the different branches of when/elsewhen must have the same set of component references on the left-hand side.
• In an equation section, the branches of an if-then-else clause inside when-clauses must have the same set of component references on the left-hand side, unless the if-then-else have exclusively parameter expressions as switching conditions.

A when clause shall not be used within a function class.

[Example:

Algorithms are activated when x becomes > 2:

   when x > 2 then
     y1 := sin(x);
     y3 := 2*x + y1 + y2;
   end when;

Algorithms are activated when either x becomes > 2 or sample(0,2) becomes true or x becomes less than 5:

   when {x > 2, sample(0,2), x < 5} then
     y1 := sin(x);
     y3 := 2*x + y1 + y2;
   end when;

For when in equation sections the order between the equations does not matter, e.g.,

 equation
   when x > 2 then
     y3 = 2*x +y1+y2; // Order of y1 and y3 equations does not matter
     y1 = sin(x);
   end when;
   y2 = sin(y1);

The needed restrictions on equations within a when-clause becomes apparent with the following example:

   Real x, y;
equation
   x + y = 5;
   when condition then
      2*x + y = 7;         // error: not valid Modelica
   end when;

When the equations of the when-clause are not activated it is not clear which variable to hold constant, either x or y. A corrected version of this example is:

   Real x, y;
equation
   x + y = 5;
   when condition then
      y = 7 - 2*x;        // fine
   end when;

Here, variable y is held constant when the when-clause is de-activated and x is computed from the first equation using the value of y from the previous event instant.

For when in algorithm sections the order is significant and it is advisable to have only one assignment within the when-clause and instead use several algorithms having when-clauses with identical conditions, e.g.,

 algorithm
   when x > 2 then
     y1 := sin(x);
   end when;
 equation
   y2 = sin(y1);
 algorithm
   when x > 2 then
     y3 := 2*x + y1 + y2;
   end when;

Merging the when-clauses can lead to less efficient code and different models with different behaviour depending on the order of the assignment to y1 and y3 in the algorithm.]

A when clause

 algorithm
   when {x>1, ..., y>p} then
     ...
   elsewhen x > y.start then
     ...
   end when;

is equivalent to the following special if-clause, where Boolean b1[N] and Boolean b2 are necessary because the edge() operator can only be applied to variables

   Boolean b1[N](start={x.start>1, ..., y.start>p});
   Boolean b2(start=x.start>y.start);
 algorithm
   b1:={x>1, ..., y>p};
   b2:=x>y.start;

   if edge(b1[1]) or edge(b1[2]) or ... edge(b1[N]) then
     ...
   elseif edge(b2) then
     ...
   end if;

with "edge(A)= A and not pre(A)" and the additional guarantee, that the algorithms within this special if clause are only evaluated at event instants.

A when-clause

 equation
   when x>2 then
     v1 = expr1 ;
     v2 = expr2 ;
   end when;

is equivalent to the following special if-expressions

   Boolean b(start=x.start>2);
 equation
   b  = x>2;
   v1 = if edge(b) then expr1 else pre(v1);
   v2 = if edge(b) then expr2 else pre(v2);

The start-values of the introduced Boolean variables are defined by the taking the start-value of the when-condition, as above where p is a parameter variable. The start-values of the special functions initial, terminal, and sample is false.

When clauses cannot be nested.

[Example:

The following when clause is invalid:

   when x > 2 then
     when y1 > 3 then
       y2 = sin(x);
     end when;
   end when;

]