Add Code Example for Event Mode with Clocks

[MarioHarter]

Noting that the concept of Clocks is often difficult for newcomers to the FMI standard, and following the discussion in Issue #2079, I believe it is highly valuable to include a clarifying code example. The existing Co‑Simulation examples do not sufficiently cover Clocks, which can make the Event Mode specification hard to fully understand.

This PR introduces:

• A short note pointing out that the current Event Mode example does not consider Clocks.
• A complete Event Mode code example including Clocks and Clocked Variables.
  To keep the example as accessible as possible, it intentionally does not cover early return or intermediate updates.
• For ease of discussion within this PR, the full example is currently included inline. This can be refactored or moved as needed once we agree on the final content.

Feedback is very welcome.

[MarioHarter]

Update: Added handling for the first-time transition into Event Mode. The system enters Event Mode directly following ExitInitializationMode, which appears to happen without an explicit EnterEventMode invocation

[chrbertsch]

FMI Design Meeting:
Christian: Great initiative.
Torsten: We switched to compilable C-Code, even pseudocode will be used by someone ...
Pierre: Perhaps some diagrams are more helpful. (Timing, communication protocol diagrams, also showing different FMUs interacting ...)
Christian: perhaps in the implementer's guide.
Torsten S.: for multiple FMUs we could refer to the container FMU implementation.
Pierre: here we need more the abstract view.
Masoud: We could test this code on the examples https://github.com/modelica/fmi-clocks-sandbox/. I will look into this

[MarioHarter]

@masoud-najafi To validate the issue here, I reviewed the outputs of your example C2_clocked_toggle. The section

"time";"time";"AmplitudeUP";"AmplitudeDown";"Output";"clkin"
(...)
0.3;0.3;1;-1;1;0
0.3;0.3;1;-1;1;0
0.3;0.3;1;-1;-1;1
0.3;0.3;1;-1;-1;0
(...)

suggests to me that some getting and setting of clocks and clocked variables must already be happening inside the UpdateDiscreteStates() loop - even in this reduced scenario without variable step size, early return, or intermediate updates.
Do you agree?

(Also, I was wondering which tool you used to generate this output?)

[masoud-najafi]

@masoud-najafi To validate the issue here, I reviewed the outputs of your example C2_clocked_toggle. The section

"time";"time";"AmplitudeUP";"AmplitudeDown";"Output";"clkin"
(...)
0.3;0.3;1;-1;1;0
0.3;0.3;1;-1;1;0
0.3;0.3;1;-1;-1;1
0.3;0.3;1;-1;-1;0
(...)

suggests to me that some getting and setting of clocks and clocked variables must already be happening inside the UpdateDiscreteStates() loop - even in this reduced scenario without variable step size, early return, or intermediate updates. Do you agree?

(Also, I was wondering which tool you used to generate this output?)

The given result in the csv file is just to show the form of the resulting curve and does not indicate how/how many times or where get/getClock or set/setXX have been called. If your results LOOKS LIKE this curves, that should be fine.
The FMUs have been tested in Twin Activate. The free student version registered with personal or academic emails can also be used to test the FMUs.

[clagms]

thank you for the example! I think that at the moment it is violating the standard (See my comments). Also see my other comments.

[chrbertsch]

Mario: the comments have been addressed, please review

[masoud-najafi]

Hi,
I checked the code. The code is correct, but IMHO not comprehensive. Many important items are still missing, such as:
-- Setting non-clocked inputs ( also during during the event iteration)
-- Getting clocked and non-clocked outputs
-- handling dependent output clocks
-- handling independent output clocks
-- handling changing clocks
-- handling count-down clocks
-- iteration in event mode

It's a good time to add these items to the spec, but If you think it's out of scope of this PR, then I approve this PR.

[MarioHarter]

Thank you for the feedback @masoud-najafi

I agree that the points you’ve raised would be very worthwhile additions to the FMI standard. However, I intentionally scoped this PR to focus on a simple implementation.

While this sacrifices some nuance, the primary goal is to establish a foundational code example for clocked variables. By keeping the logic simple, we ensure the core clock mechanics aren't obscured by other code. So let’s keep this as the "Hello World" of clocked variables and address the further topics in separate issues! I’m happy to help capture these suggestions and created issue #2127 for this.

[clagms]

Maybe a remark can be added next to the example showing what is not covered? This would give people an idea of how simplistic the example is... best to not delude the reader into thinking clocks are simple?

[MarioHarter]

Good idea! I was able to edit the section introduction so that the scope of this example is clearer. (I did not include a list of things omitted, as the other examples do not either, but I specified the focus of this example.)

[masoud-najafi]

Since the purpose of this PR is not to demonstrate the use of all clock types, it should be stated that the example code handles only "independent output clocks", that is, clocks with unpredictable timing that are detected during doStep().