Useful example why fmi3UpdateDiscreteStates might request discreteStatesNeedUpdate

[chrbertsch]

Discussed in #2148

^{Originally posted by klausschuch March 24, 2026}
While discussing #2133, the following question came up:
Why would an FMU set discreteStatesNeedUpdate=True in a fmi3UpdateDiscreteStates() call?
I can only come up with very artificial example but have no idea for a good model that needs this.
According to the "Equations and Actions" table in https://fmi-standard.org/docs/3.0.2/#EventMode, the values returned by the Get... calls should already consider the new discrete state anyway. Note, that this is unrelated to the fact if fmi3EvaluateDiscreteStates got called or not.

[chrbertsch]

Klaus: Perhaps the problem is that we do not define what event iteration is ...

[chrbertsch]

We need a definiction / clarification of what updateDiscreteStates does, see also discussion in #2050 w.r.t. time-based changing clocks

[otronarp]

We do have it in our glossary:

An importer can iteratively call fmi3Set{VariableType} and fmi3Get{VariableType} e.g. to solve algebraic loops during an event and during a super-dense time instant. When reaching a consistent state, changes to discrete variables may be triggered. Such a discrete (state) change may require another solution of an algebraic loop in the next super-dense time instant. These discontinuous changes can repeat until the participating FMUs or the master decide that no further iteration is needed. An example for a system that can be simulated with event iteration is a powertrain with multiple clutches distributed in several FMUs. The decision which clutch is open, which is closed and which is slipping can be determined with event iteration.

Event iteration in Modelica is described towards the end of this page: https://specification.modelica.org/maint/3.6/modelica-dae-representation.html

with the following pseudo code:

known  variables: x, t, p
unkown variables: dx/dt, y, z, m, pre(z), pre(m), c

// pre(z) = value of z before event occured
// pre(m) = value of m before event occured
loop
  solve (1) for the unknowns, with pre(z) and pre(m) fixed
  if z == pre(z) and m == pre(m) then break
  pre(z) := z
  pre(m) := m
end loop

Now, if you want to take a system that is solved like that and split it into connected FMUs (ME), in the general case you need to iterate on the hole system one iteration at a time to arrive to the same solution.

The discreteStatesNeedUpdate is simply the mechanism for the FMU to say that has not yet reached a stable solution (if z == pre(z) and m == pre(m) then break).

[chrbertsch]

We do have it in our glossary:

An importer can iteratively call fmi3Set{VariableType} and fmi3Get{VariableType} e.g. to solve algebraic loops during an event and during a super-dense time instant. When reaching a consistent state, changes to discrete variables may be triggered. Such a discrete (state) change may require another solution of an algebraic loop in the next super-dense time instant. These discontinuous changes can repeat until the participating FMUs or the master decide that no further iteration is needed. An example for a system that can be simulated with event iteration is a powertrain with multiple clutches distributed in several FMUs. The decision which clutch is open, which is closed and which is slipping can be determined with event iteration.

This was removed in a7f2a2d ...

[chrbertsch]

FMI Design Meeting:
@otronarp : I will look into this