Clarify meaning of when-clause

[casella]

Section 8.3.5 defines when-equations:

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

and then adds

If expression is a clocked expression, the equation is referred to as a clocked when-clause (section 16.6) rather than a when-equation, and is handled differently

Unfortunately, the rest of the text of the language specification mostly refers to when-clause, rather than when-equation, e.g.:

• Section 3.7.5, definition of Operator 3.24 pre(y): "If v and pre(v) are only used in when-clauses..."
• Section 3.8.5 definition of discrete-time expressions: "Discrete-time expressions are ... Expressions in the body of a when-clause"
• Section 4.5 definition of component variability: "A discrete-time variable vd is a variable that is discrete-valued (that is, not of Real type) or assigned in a when-clause".
• etc. etc.

This is a bit confusing, because one may think that when-clause is synonymous with clocked when-clause, whereas I understand it is synonymous with when-equation.

I would suggest to say that explicitly.

[henrikt-ma]

I now see why I thought that "when-clause" might refer to just one of the branches. In an if-equation, we use if-clause to just refer to the first branch:

• https://specification.modelica.org/master/equations.html#if-equations

As long as this remains, I don't think we can expect readers to understand precisely what is meant by "when-clause", as they may be familiar with the terminology we use for if-equations and not realize that they should go and dig up a different way of using clause when it comes to when.

[HansOlsson]

I agree that there's a problem and we should make them similar.

However, the problem is that we normally want to refer an if/elseif-banch in the same way and similarly for when/elsewhen-branches.
By treating when-clause as both when and elsewhen-branches we handle the three cases above.

So, by considering if-clause as only the if-branch we introduce a severe problem in 3.8.5 (it also applies to elseif right?), whereas 8.3.4 and 11.2.6 have to repeat if-clause or elseif-clause, which seems messy.

I would propose:

• when-clause refer to entire when and elsewhen construct
• if-clause refer to entire if, elseif, and else construct
• we use if-branch, elseif-branch etc to refer to the individual parts
• and body or bodies as the insides
• expression(s) for the if-branch, elseif-branch conditions

[henrikt-ma]

I would propose:

Sounds workable, even though it doesn't match my previous intuition which war more in line with the old if-clause terminology referring to what is here called a branch.

• when-clause refer to entire when and elsewhen construct
• if-clause refer to entire if, elseif, and else construct
• we use if-branch, elseif-branch etc to refer to the individual parts

I suppose this includes when-branch and elsewhen-branch?

Am I right that a "when-clause branch" should refer to either a when-branch or an elsewhen-branch? (At least for if-clauses, it is good to have a dedicated name for the possibly absent else-branch, so I don't think we would like "if-branch to refer to any of the branches, and then for symmetry we shouldn't use "when-branch" to refer to any of the branches of a when-clause.)

• and body or bodies as the insides
• expression(s) for the if-branch, elseif-branch conditions

We call them conditions, right?

[HansOlsson]

Language group: Would be good with additional input, but seems ok.

Not good:

• Different rules for if and when-
• Nice to have one name for "entire thing"
• Currently seems some inconsistent uses

Depends on frequently it is used. Try to collect statistics, and then make PR -> @HansOlsson

[HansOlsson]

On current master:

Clause could be either entire thing or one branch, but in the latter case "else..." is missing:

• When-clause https://specification.modelica.org/master/introduction1.html#scope-of-the-specification
• When-clause https://specification.modelica.org/master/operators-and-expressions.html#arithmetic-operators (should use "body of a when-clause")
• https://specification.modelica.org/master/operators-and-expressions.html#event-related-operators-with-function-syntax (should use "body of a when-clause" - only done for reinit)
• https://specification.modelica.org/master/operators-and-expressions.html#discrete-time-expressions (both if-clause and when-clause). The if-clause part is a bit more complicated.
• https://specification.modelica.org/master/class-predefined-types-and-declarations.html#component-variability (some should use "outside a body of a when-clause")
• https://specification.modelica.org/master/class-predefined-types-and-declarations.html#balanced-models
• https://specification.modelica.org/master/equations.html#defining-when-equations-by-if-expressions-in-equality-equations (but should use "body of...")
• https://specification.modelica.org/master/equations.html#equations-within-when-equations
• https://specification.modelica.org/master/equations.html#events-and-synchronization
• https://specification.modelica.org/master/equations.html#initialization-initial-equation-and-initial-algorithm

Clause only meaning one branch:

• https://specification.modelica.org/master/equations.html#if-equations (and using if-equation for entire thing)
• https://specification.modelica.org/master/equations.html#reinit in general but it requires some thought, and it is incorrect for: "During simulation, non-state variables should be chosen in such a way that variables with an applied reinit are selected as states at least when the corresponding when-clauses become active"
• https://specification.modelica.org/master/statements-and-algorithm-sections.html#if-statement

Clause meaning entire thing:

• https://specification.modelica.org/master/equations.html#when-equations

I would thus propose the following:

• when-clause refers to the entire when/elsewhen-equation or -statement
• a branch of a when-clause
• a body of a when-clause refers to one of the bodies of

For a when-equation or when-statement:

when c1 then
   bw1
elsewhen c2 then
   bw2
end when;

if c1 then
   bi1
elseif c2 then
   bi2
else 
   bi3
end if;

• when-clause and if-clause refers to entire thing
• body of a when-clause refer to bw1 and bw2
• body of an if-clause refer to bi1, bi2, and bi3
• branch of a when-clause refer to "when c1 then bw1" and "elsewhen c2 then bw2"
• branch of an if-clause refer to "if c1 then bi1", "elseif c2 then bi2", "else b3", "if-branch", "elseif-branch" and "else-branch" have the obvious meaning

I also noted another minor issue: "when-equations can only occur within if-equations and for-equations if the controlling expressions are exclusively evaluable expressions." consider:

model Ok
  parameter Boolean b=true;
  Real x;
  Real a;
equation 
  if b then
    when sample(1, 1) then
      reinit(x, 0);
    end when;
    a = 1;
  elseif x > 0 then
    a = 2;
  else
    a = 3;
  end if;
  der(x) = 1 - x;
end Ok;

and:

model Bad
  parameter Boolean b=true;
  Real x;
  Real a;
equation 
   if x > 0 then
    a = 1;
   elseif b then
    when sample(1, 1) then
      reinit(x, 0);
    end when;
    a = 2;
  else
    a = 3;
  end if;
  der(x) = 1 - x;
end Bad;

It seems excessive to require that the entire if-equation has an exclusively evaluable condition (see Ok, where x>0 doesn't matter for the when-clause), and on the other hand it is clearly insufficient to require that condition of the elseif-branch itself is evaluable.
We could add a clarification like:

For an if-equation this requires that all the conditions of the if-branch containing the when-equation and all preceding if-branches are evaluable.

[henrikt-ma]

• branch of an if-clause refer to "if c1 then bi1", "elseif c2 then bi2", "else b3", "if-branch", "elseif-branch" and "else-branch" have the obvious meaning

It may be easier said than done that "if-branch" has the obvious meaning, because would be so easy to accidentally write "if-branch" when the correct thing to write would be "branch of an if-clause". My recommendation would be to try very hard to avoid speaking of both "if-branch" and "elseif-branch", and only speak of "else-branch" where we need to explain what it means to not have one.