see discussion on modelica/fmi-standard#1703.

The workflows do not seem to work for publishing the generated documents
https://modelica.github.io/fmi-guides/main/fmi-guide/

Woule be great if this would be fixed not that the repo is public.

As discussed in the F2F meeting in Berlin, it makes sense to clarify that the tick of a time-based input clock can cause activation of a triggered input clock.

(from a discussion with Pierre)

We should better explain, under which conditions and for which use cases to use SE (e.g. realtime conditions on a HiL system with mutliple vECUs on a a platform, where the actual code execution takes place) and when better not to use it (and use e.g. CS)

There should be a short text in the standard, and more explanation and discussion of this topic in the implementers (/users) guide

Note that for FMI 3.0 support, a new release of SSP is needed for the new data types.

Having the FMI logo and ProSTEP logo on top of the implementer's guide might lead to the impression that FMI is an ProSTEP subproject?

As the MoU (https://github.com/modelica/fmi-design/blob/master/ProSTEP/MoU_2017/2017-07-01-Memorandum-of-Understanding-MA-Prostep.pdf) is between MA (with all its MAPs) and ProSTEP, it might make sense to add the Modelica Association logo somewhere to the Implementer's Guide? (Source: https://github.com/modelica/MA-Logos).

3 logos seems a lot, but I think all organizations should be shown.
What do you think?

(see email from Torsten B. on 10.10.2021)

We removed the following from the description of the start attribute:

[If the initialization shall be modified from the importer (for example, changing from initialization of states to steady-state initialization), it is also possible to use the <> value as iteration variable of an algebraic loop: using an additional condition in the environment, such as latexmath:[{\dot{x} = 0}] , the actual <> value is determined.]

This should be enhanced and added in here.

see modelica/fmi-standard#1865

There is currently no motivation why some features are selected for certain profiles.
Fori instance why is any feature needed for Basic co-simulation

Move to optional:

• resizable Inputs/Outputs : For most tools, changing the IO during runtime is impossible and we are calling this "Basic" which is, in my opinion, a contradiction

see modelica/fmi-ls-xcp#21 (comment)

... that can be reference in compatibility information (modelica/fmi-standard.org#450)

see also https://github.com/modelica/fmi-design/tree/master/Meetings/2023/2023-06-13-FMI-Steering#discussion-of-fmi-30-feature-profiles

This issues handles the production of initial content for the fmi-ls-bus guide.

point out the obvious and not so obvious ways to resolve connections between structured naming arrays and native arrays in the IG,

(from modelica/fmi-standard#1799 (comment))

Required:
FMUs must be self-contained, no dependencies on installed tools or libraries,
No connection to an external license server

for instance: author could not just be John Doe but better John Doe, [email protected]
What about other fields?
Similar additions?

Just like the specification the IG should make a remark such as "To prepare the FMU code to run reliably on preemptive systems FMI functions must not change global settings." in the https://modelica.github.io/fmi-guides/main/fmi-guide/#_global_state section

How to check an export in that case?
some feature is maybe easy, but sting IO, if there is no stings in the model etc,
You could claim support for dynamic array sizes but only support for trivial models. (e.g. linear system)

FMI Standard, 2.2.12. Getting Partial Derivatives:

• definition of adjoint derivatives is prone to misunderstandings because the seed and sensitivity vectors are not just tranposed but have different dimensions

Implementer's Guide, 9.1. Partial Derivatives:

• the examples are hard to follow without the basic definitions of directional and adjoint derivatives
• Add example for matrix-free Jacobian-vector products to directional derivatives, e.g. for Krylov methods
• Adjoint derivatives should be chapter 9.1.2 instead of 9.1.1.1 (?)

For many applications, representing a terminal with a simple rectangle would be good enough.

I'm not an XSD expert, but I believe that the definition

                <xs:attribute name="iconBaseName" type="xs:string" use="required"/>

allows an empty string.

The FMI3 specification states that the value is mandatory and also requires a PNG to be present.

I propose that we allow an empty string and for such cases define the graphics as a rectangle drawn in "defaultConnectionColor". Filled or not could be implementation defined.

In FMU simulations of colleagues I often see problems such as divsion by zero in FMUs that do not have proper start values for inputs.

Example: A CS-FMU exported from Dymola.
If the inputs of the model do not have a defined start value, in some importing tools (such as AMESim) one gets errors such as division by zero when dividing by one of the inputs, even if the input is connected with a non-zero source in the importing tool.

Reason: the input values are not set by some importing toolsbefore using them

Remedy: e.g. in Dymola define a start value for the input blocks used to define the inputs of the FMU to be generated.

Having plausible start values increases the chance that the FMU gets simulated correctly in different tools.

btw: is it required by the standard, that inputs are set in initialization mode, before the initialization is performed? Or is it only allowed and recommendable to set the inputs before using them in initialization?

It seems a number of the issues addressed in the non-normative text at the end of 5.1 would better fit the IG.
Please consider moving text.
We have not yet removed text from there as we are unsure which parts.

First of all, great work! It reads very well and already has a lot of useful content!

The following are notes from a quick read. Sorry that they are all gathered here, but it would be cumbersome to create separate issues for small things.

• In "Chapter 1. Introduction", we should probably make it clear that the guide is best read after having read the standard. The text clearly makes this assumption in many places.
• We should always use the same terms to refer to the importer and exporter, as per the fmi standard. Sometimes we use "importing implementation" and "master", and "co-simulation master", to refer to the same thing. Same with "exporting implementations" and "Implementations that produce FMUs".
• In "Robust participation, including testing with a relevant selection of available releases, is recommended.", I would make it clear that testing FMUs should be incorporated into the integration tests of the tool provider.
• In "FMU exporting implementations should also use the FMU Compliance Checker", I think we should include a link to a place where we collect links to all FMI utilities. It could be a wiki page, or part of https://fmi-standard.org/ . There we would classify tools according to whether they help exporters or importers, and it would include things such as the FMU Compliance Checker, Reference-FMUs, fmu-builder, VDMCheck and UniFMU.
• In "Exchange of FMUs can be eased tremendously if an option exists to generate FMUs that do not require license mechanisms at the receiving party.", maybe we need to detail what the alternatives are, to ensure IP protection without having to use license mechanisms.
• In "detailed information should be provided using the ports and icons information.", add a reference to where the ports and icons standard is defined.
• The following are potentially ambiguous references:
  • "allow the user to easily add those information items"
  • "Where that is not feasible, implementations should prefer"
  • "Ideally this support should include"
• In each subsection, we could use formatting to make it clear what are recommendations that apply to importers and what are recommendations that apply to exporters.
• In " the searched paths will be based on the importer executable", maybe clarify what "based on" means.
• In "preference should be given to native arrays over structured ", maybe clarify what native here means.
• In "Note especially that null pointers are not valid for any of the string arguments to these functions, unless explicitly allowed.", maybe clarify where it would be expicity allowed.
• In "or in combination with Section 6.2, as described below.", maybe clarify what is actually being combined.
• Avoid ambiguities by adding oxford commas to "However the exact semantics, capability flags and rules when to call this function vary between all
  major releases of FMI" so it becomes "However the exact semantics, capability flags, and rules when to call this function, vary between all
  major releases of FMI"
• Typos:
  • during creation of an FMU: Imports should, if more suitable
  • "false" should be "fmi2False" and "true" should be "fmi3True", or something like that.

see modelica/fmi-standard#1714 (comment)

For example content like

However, just like in FMI 2.0, it could in principle also be implemented by activating the model equations only at the first event iteration and returning always newDiscreteStatesNeeded == fmi3False from <>.

Furthermore, the discrete-time <<state,states>> are not updated by <>, but as first action before the discrete-time equations are evaluated, in order that latexmath:[^{\bullet}\mathbf{x}_d] (= value at the previous Lucid Synchrone/Modelica 3.3 clock tick) and latexmath:[\mathbf{x}_d] (value at the latest Lucid Synchrone/Modelica 3.3 clock tick) have reasonable values between Lucid Synchrone/Modelica 3.3 clock ticks.

Move from required to recommended:

• Tunable Parameters
• Store/Restore FMU State
• Serialize/Deserialize FMU State
• String Inputs/Outputs
• Resizable Input/Output Arrays
• Resizable Input/Output Arrays with Size-Dependencies
• Resizable Parameter Arrays
• Resizable Parameter Arrays with Size-Dependencies

Remove as the shall be supported anyway by all FMI3 FMUs:

• New Integer Types

There are extensive use case descriptions in the FMI Standard that are likely better suited for this guide, see 2.4.3 Physical Units.
Move only use case description, do not move all examples.

In 2.4.8. Model Structure, there are large examples for dependencies and dependencyKind.
These should be moved to here.

Add specific wording to also point out that open source licenses might have to be shipped with the FMU, and/or might also be placed in the FMU documentation folder.

As the features profiles are not yet released , are at least not prominently referenced from other websites and in contrast to the implementers guide are not called a "guide", now would still be an opportunity to move them to a separate repository.
This would lead to a clearer structure and simpler release process and versioning

Add a note about connecting clocked variables of clocks with different properties.
Maybe even how to connect any different kind of variables "correctly".

This is beside the information that is already contained in the IG.

The issue was raised how cybersecurity can be ensured w.r.t to FMU exchange.

E.g., how can we make sure that an FMU containing binaries is still the same as it was compiled by a supplier (and not manipulated by a third party)?

These topics are not covered by the FMI standard, but any kind of authentication mechanisms that can be used for the validation of digital artefacts cab be used for FMUs, e.g. secure hash values that are exchanged together with the FMU.

We should comment on this in the IG, and provide recommendations or links to other standards etc.

See also 4.3 of https://2017.international.conference.modelica.org/proceedings/html/submissions/ecp17132329_DurlingPalmkvistHenningsson.pdf

Discussion:

Christian: Perhaps split into optimization and "AI" profile, where adjoint derivatives would be mandatora, otherwise recommeneded
Make "Resizable Parameter Arrays" recommended

Discussion:

Pierre: We could rename it to "Perception sensor profile"
Matthias: Downgrade "Variable Co-Simulation Communication Step Size" to recommended

due to the change compared to modelica/fmi-standard#1122

We removed the following sentence in the standard from non-normative text at the entirely wrong place (4.4 description of fixedInternalStepSize.
But this should be mentioned somewhere:
The co-simulation algorithm should calculate the communication points by multiplying (number_of_steps * step_size) instead of repeatedly incrementing (time += step_size) to avoid the accumulation of numerical errors

-fno-gnu-unique On systems with recent GNU assembler and C library, the C++ compiler uses the "STB_GNU_UNIQUE" binding to make sure that definitions of template static data members and static local variables in inline functions are unique even in the presence of "RTLD_LOCAL"; this is necessary to avoid problems with a library used by two different "RTLD_LOCAL" plugins depending on a definition in one of them and therefore disagreeing with the other one about the binding of the symbol. But this causes "dlclose" to be ignored for affected DSOs; if your program relies on reinitialization of a DSO via "dlclose" and "dlopen", you can use -fno-gnu-unique.

as it gets confusing that in the profiles many features that are not present in FMI2.0.

Additionally we should for the individual profiles drop some basic features that we expect for all profiles to be supported such as "New Integer types"

In "FMI functions must not change global settings which affect other processes/threads." add the following, or similar:

[This property ensures that functions of different FMU instances can be called safely in any order.
Additionally, they can be called in parallel provided the functions are called in different processes.
If an FMI function changes, for example, the floating point control word of the CPU, it must restore the previous value before return of the function.
// TODO shift the following to implementer´s guide
For x86 CPUs, the floating point control word is set using the fldcw instruction.
This can be used to switch on additional exceptions such as floating point division by zero.
An FMU might temporarily change the floating point control word and get notified on floating point exceptions internally, but has to restore the flag and clear the floating point status word before return of the respective FMI function.]

_[A clock's <<priority>> information is required to support the scheduled execution of several model partitions._ _In particular the <<preemption-support, preemption support>> is based on these priorities._ _It is therefore important to restrict the number of distinct priority levels for an FMU to available priority levels on the target platform and/or to avoid unnecessary computational overhead._ _A common number of different priority levels is, e.g., 100 (0 to 99), as defined in Linux based operating systems.]_

Note: already removed in standard text.

General stuff in sections 4&5, kind-specific content to 6.7.8.9.

In section 3.1.2 there is a reference to section 3.8 which does not exist

Some of the fallbacks (discussed in sections 3.8 and 5.1)

"Support" should be clarified: importers should simply ignore binaries for platforms they do not care about. If we are not stating this this clearly, one might read this as if some special functionality is required.

For exporters, this is different: Do we actually mean to say that exporters should support arbitrary non-desktop platforms during generation? I sure hope not... we need to clarify.

Regarding: https://modelica.github.io/fmi-guides/main/fmi-profiles/#_basic_hil_sensor_hil_profile

I propose to move "Scheduled Execution Interface" from required to optional.

"New Integer Types" have to be supported anyway, we can remove this.

"Source Code FMUs" and "Binary FMUs for non-Desktop Platforms (e.g. HiL)" should be alternatives, not both have to be supported

If an FMU/CS is instantiated with eventModeUsed==True and earlyReturnAllowed==False, what the FMU is supposed to do if an internal unpredictable event such as zero-crossing event happens inside the FMU.
If an event happens between [cp, cp+step], I am not sure if delaying the event and declare the event at cp+step would be a good solution. But if this is the way to go, it might be worthy to mention it somewhere.

Move to "recommended":

• Store/Restore FMU State
• Source Code FMUs
• Binary FMUs for non-Desktop Platforms (e.g. HiL)
• Scheduled Execution Interface

• update introductory text https://github.com/modelica/fmi-guides/blob/main/fmi-guide/1___introduction.adoc, e.g. " This is a development version of the guide that has not been reviewed or finalized in any way."
• do we need a version number / Tagging currently it states"version main-7f6ef479350d06fbdc042eca7e236947acd5b42f, 2023-02-24 ". But the introduction talks about releases https://github.com/modelica/fmi-guides/releases

See modelica/fmi-standard#1015 (comment) and Remark 1 in https://fmi-standard.org/docs/3.0-dev/#math-model-exchange "Calling sequences" should be mentioned or perhaps moved to the implementers guide