Skip to content

Clarify rules on fmi3GetInterval*/fmi3GetShift* functions with regards to periodic input clocks #2018

@pmai

Description

@pmai

The standard seems to suggest that these functions can be called for clocks with constant/fixed/tunable intervalVariability - at least under some circumstances - in Table 5 by listing as related API:

  • constant:

    fmi3SetClock in EventMode, fmi3ActivateModelPartition in ClockActivationMode, fmi3GetInterval and fmi3GetShift in InitializationMode

However for fixed/tunable it lists:

  • fixed:

    fmi3SetClock in EventMode, fmi3ActivateModelPartition in ClockActivationMode,

    • if intervalDecimal is defined, fmi3SetInterval in InitializationMode,
    • if intervalDecimal is not defined, fmi3GetInterval and fmi3GetShift in InitializationMode

So interestingly, for fixed/tunable you can only call fmi3GetInterval/fmi3GetShift if no interval is provided in the modelDescription.xml.

While Table 6 then just generally states on T_interval_i:

The time interval until the next Clock tick, defined differently for the different Clock types. Tinterval,i
can be set with fmi3SetIntervalDecimal or retrieved with fmi3GetIntervalDecimal as floating point value, or as rational number using fmi3SetIntervalFraction or fmi3GetIntervalFraction.

which might or might not suggest that fmi3GetInterval* can always be called.

Furthermore the definition of fmi3GetInterval* then provides wording that does not suggest anyone thought of the semantics of calling them for periodic clocks:

  • qualifiers is an array of size nValueReferences to retrieve the Clocks qualifiers.
    qualifiers describes how to treat the intervals and counters arguments and is defined as:

...

with the following meanings:

  • fmi3IntervalChanged is returned to indicate that the value for the interval has changed for this Clock.
    Any previously returned intervals (if any) are overwritten with the current value.
    The new Clock interval is relative to the time of the current EventMode or ClockUpdateMode in contrast to the interval of a periodic Clock, where the interval is defined as the time between consecutive Clock ticks.
    In Scheduled Execution this means that the corresponding model partition must be scheduled or re-scheduled (if a previous call to fmi3GetInterval returned fmi3IntervalChanged).
  • fmi3IntervalUnchanged is returned if a previous call to fmi3GetInterval already returned a value qualified with fmi3IntervalChanged which has not changed since.
    In Scheduled Execution this means the corresponding model partition has already been scheduled.
  • fmi3IntervalNotYetKnown is returned for a countdown-aperiodic-clock,countdown Clock for which the next interval is not yet known.
    This qualifier value can only be returned directly after the Clock was active and previous calls to fmi3GetInterval never returned fmi3IntervalChanged (nor fmi3IntervalUnchanged).
    In Scheduled Execution this return value means that the corresponding model partition cannot be scheduled yet.

None of the options provided seem to take constant (or even just periodic) clocks into account, and hence it is unclear what should be returned:

  • fmi3IntervalChanged seems to assume we are in Event Mode, but the calls allowed are in Initialization Mode, which is not Event Mode, and it also suggests the intervals are relative to some current time, which again they should not be for periodic clocks.
  • fmi3IntervalUnchanged is only allowed if fmi3IntervalChanged has been reported once, so no go for periodic/constant clocks.
  • fmi3IntervalNotYetKnown is only available for countdown clocks when the next interval is not yet known.

Taken together I think the description of this in the standard should be refined to precisely state whether and when it is allowed to call fmi3GetInterval* and what should be returned for periodic clocks.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions