Storage location for FMU output files

[modelica-trac-importer]

Reported by andreas.nicolai on 7 Nov 2014 12:03 UTC

Problem Description

FMUs may generate a large number of result data that are not part of the FMU communication. For example, an FMU of a Building Simulation Model may be connected to another FMU with control algorithms and HVAC components. The Building Simulation Model will generate a large number of internal outputs (order 1000 to 100000). Similarly, FMUs encapsulating PDE problems may generate large fields of transient data (order of variables > 1 Million when using 2D/3D grids).

In either case, exporting all variables from the model as output variables to the simulation master is not feasible (... "may not be feasible" is too weak a statement in this context).

Also, existing model implementations may have own output formats tailored to a dedicated post-processing for that specific engineering domain. These outputs would naturally be written to files from within the FMU, whenever a communication step (CoSiM) or calculation step (ModelExchange) has completed.

Assumptions about current FMU interface design

An FMU receives via the FMI v2 interface a resource path location. This path has to be treated as read-only, since it may be located in a temporary directory created by the master and removed by the master upon simulation end. Therefore, the resource path may not be used to generate output file paths from.

The location of the FMU executable/shared library may be in a read-only location, as well.

Storing absolute file paths in the FMU reduces portability, e.g. when running FMUs in cloud computing environments, where traditional file systems or paths are not available.

Fixing output paths in an FMU instance may lead to several FMU instances overwriting each others results, when several simulation runs (several masters) are being run concurrently. A likely scenario may be, when from a set of FMUs one FMU is modified/parametrized differently, the others are used unchanged. Then a variation/sensitivity study may be done in parallel with the same FMU. This may involve 100 variations computed in parallel. If the same FMU were to be used in each variation with a fixed output path, an FMU instance might overwrite results of an other FMU, or fail to write outputs altogether. A workaround would require 100 copies of potentially large FMU containers with individual output paths. This procedure may be restrictive and cumbersome.

Resulting requirements regarding the FMU Interface

The FMU must receive a persistent path to store its output files. The FMU must be able to store its outputs in a manner that suits the physical problem/implementation in the FMU, e.g. creation of subdirectories must be possible.

Ideally, this output path should be provided alognside the resource path. For example, the function fmi2Instantiate() could be extended as follows.

fmi2Component fmi2Instantiate(fmi2String instanceName,
  fmi2Type fmuType,
  fmi2String fmuGUID,
  fmi2String fmuResourceLocation,
  /* Provide a writable output location with access permissions for the FMU process */
  fmi2String fmuOutputLocation,
  const fmi2CallbackFunctions* functions,
  fmi2Boolean visible,
  fmi2Boolean loggingOn
);

Proposal for short-term workaround

The interpretation of the resource path should be explicitely changed to persistant location with read/write access to the FMU process.

Master implementations must guarantee that the content of the FMU is extracted into such a dedicated directory.

If the same FMU is instantiated several times by the master, each FMU instance must receive a unique directory (ultimately resulting in duplication of resource data of the original FMU).

---

Migrated-From: https://trac.fmi-standard.org/ticket/299

[modelica-trac-importer]

Comment by iakovn on 9 Dec 2014 08:56 UTC Andreas,

I'm wondering if the current working directory is a better and more natural place for storing output files? Different FMU instances may by default utilize instanceName to create, e.g., unique sub-directories in the current working directory for storing the output data.

Ideally, this output path should be provided alognside the resource path. For example, the function fmi2Instantiate() could be extended as follows. This would break binary compatibility with the original release, which is not desirable. An additional capability flag, e.g., producesFileOutput (default false) coupled to an additional API function, e.g., fmi2SetOutputLocation, may be a better option.

The interpretation of the resource path should be explicitely changed to persistant location with read/write access to the FMU process. As you wrote yourself a read-only or temporary location is more common for resources. In some server applications a persistent location with read/write access may actually not be available and so the requirement cannot be general.

Best regards,

Iakov

[modelica-trac-importer]

Comment by rerbacher on 9 Dec 2014 13:31 UTC We need to consider that FMUs may also run on systems that do not have a file system, or where the file system is not available in the same way as we are used to by Windows and Linux systems. A capability flag like producesFileOutput or similar is definitely a good idea. It would allow an FMI importing tool to refuse an FMU if it can't support the file system.

Rafael Gilles, dSPACE GmbH

[modelica-trac-importer]

Comment by andreas.nicolai on 17 Dec 2014 08:03 UTC Replying to [comment:1 iakovn]: #

I'm wondering if the current working directory is a better and more natural place for storing output files? Different FMU instances may by default utilize instanceName to create, e.g., unique sub-directories in the current working directory for storing the output data.

The current working directory may work in some cases, however, the FMI itself may have difficulties selecting a unique subdirectory name. Also, from the workflow/usability point of view, it would be nice to have a directory structure like:

master_dir/
  /fmu_instance_1_name
    /... files
  /fmu_instance_2_name
    /...

So that the subdirectory names match those FMU instance names used in the co-simulation master specification (instance names). Since the FMUs themselves do not know their given instance name (in the scenario where the same FMU is instantiated several times), the master has to provide the directory names.

Ideally, this output path should be provided alognside the resource path. For example, the function fmi2Instantiate() could be extended as follows. This would break binary compatibility with the original release, which is not desirable. An additional capability flag, e.g., producesFileOutput (default false) coupled to an additional API function, e.g., fmi2SetOutputLocation, may be a better option.

Agreed. Too bad, this wasn't already incorporated in the FMI 2.0 standard.

The capability flag is IMHO not necessary. If the fmi2SetOutputLocation() function is defined, it must be able for the master to call it (right after instantiation). Whether the FMU makes use of this information or not should be up the FMU.

The interpretation of the resource path should be explicitely changed to persistant location with read/write access to the FMU process. As you wrote yourself a read-only or temporary location is more common for resources. In some server applications a persistent location with read/write access may actually not be available and so the requirement cannot be general.

This was meant as a work-around (actually being used by existing master implementations). Since it is definitly not generally applicable, let's drop this option.

[modelica-trac-importer]

Comment by anonymous on 17 Dec 2014 08:12 UTC Replying to [comment:2 rerbacher]:

We need to consider that FMUs may also run on systems that do not have a file system, or where the file system is not available in the same way as we are used to by Windows and Linux systems. A capability flag like producesFileOutput or similar is definitely a good idea. It would allow an FMI importing tool to refuse an FMU if it can't support the file system.

This delegates error checking functionality from the FMU to the master. Normally, an output-writing FMU needs to create output files during initialization. If it fails to open files (path does not exist, access permissions, no file system etc.) the FMU must report such errors to the Co-Sim master. And the master will stop with an appropriate error message.

Adding a capability flag and an additional redudant check in the master would add implementation effort to master developers.

Though, there might be one benefit to the capability flag option. When an existing v2.0 FMU has been written according to the current standard, it may not have an fmi2SetOutputLocation() function. If this function were declared optional, than the capability flag allows supporting both FMUs with and without the function.

However, considering the still limited number of existing FMU 2.0 implementations, it might be feasible to make the fmi2SetOutputLocation() function mandatory and skip the option-flag extension.

If the fmi2SetOutputLocation() function is to come, I would be strongly in favor for a mandatory addition, since for all non-trivial FMUs output writing is a central feature, both for model developers and for users.

[modelica-trac-importer]

Comment by iakovn on 17 Dec 2014 09:03 UTC Replying to [comment:3 andreas.nicolai@…]:

Replying to [comment:1 iakovn]: #

I'm wondering if the current working directory is a better and more natural place for storing output files? Different FMU instances may by default utilize instanceName to create, e.g., unique sub-directories in the current working directory for storing the output data.

The current working directory may work in some cases, however, the FMI itself may have difficulties selecting a unique subdirectory name. Also, from the workflow/usability point of view, it would be nice to have a directory structure like:

master_dir/
  /fmu_instance_1_name
    /... files
  /fmu_instance_2_name
    /...

So that the subdirectory names match those FMU instance names used in the co-simulation master specification (instance names). Since the FMUs themselves do not know their given instance name (in the scenario where the same FMU is instantiated several times), the master has to provide the directory names.

Well, FMUs do know their instance names which should be unique from fmi2Instantiate call. So, your proposal matches mine if you accept that master_dir is the current working directory by default.

The capability flag is IMHO not necessary. If the fmi2SetOutputLocation() function is defined, it must be able for the master to call it (right after instantiation). Whether the FMU makes use of this information or not should be up the FMU.

This is more a matter of taste and style. A few other functions in the FMU spec are of similar nature and those are 'guarded' by capability flags. Adding new mandatory functions to FMI2 spec is to be avoided IMHO unless absolutely necessary.

[modelica-trac-importer]

Comment by torstenblochwitz on 17 Dec 2014 16:00 UTC From my Point of view, it is not necessary to introduce something new here.

Some time ago we discussed about introduction of special parameters or functions for setting of solver parameters for Co-Simulation FMUs. We discarded that idea since this feature can be realized by normal fixed parameters. The same can be done for storage location for additional results by providing a simple string parameter for that. In this way the users have full control and existing functionality (handling of parameters) can be used on master side.

[modelica-trac-importer]

Comment by Andreas Nicolai on 5 Jan 2015 10:02 UTC Replying to [comment:6 torstenblochwitz]:

From my Point of view, it is not necessary to introduce something new here. ... The same can be done for storage location for additional results by providing a simple string parameter for that. In this way the users have full control and existing functionality (handling of parameters) can be used on master side.

The string-parameter option might be a convenient workaround for some FMUs until a proper extension of the standard is in place.

However, I strongly disagree with the view that such a string parameter is sufficient:

First: While the option with a string parameter would work, it would then be a matter of convention that shall be followed by FMUs. And with a convention comes the name for that location parameter that needs to be standardized as well "OutputLocation", "OutputFolder", ...?? So, making it part of the FMU standard is meaningful. Otherwise a lot of different FMUs might be created by different groups which can then not be combined in a flexible way by a master.

Second: The output file location must be specified as part of the FMU connections in the CoSim-Master description file. With respect to a meaningful workflow this may be unsuitable (e.g. think about creating a variation of a simulation scenario and now you have to edit all string parameters of all FMU instances before running the simulation). Also, when only the master knows suitable storage locations (due to knowledge of execution environments, commandlines arguments etc.) it needs to generate connection information that may conflict with user-specified connections - the user might want to hard-code an output file location, while the master wants to set another. This type of conflict management is unecessary and should be avoided.

Third: An "output file location" is exactly the type of meta-data as the "resource file location": 1. does not change over lifetime of simulation, 2. is specific to FMU instance, 3. needs to be known at instantiation of FMU. IMHO, it would be inconsequent/inconsistent to use two different mechanisms to pass the same type of information to an FMU.

Fourth: it is not guaranteed that the string parameter is set sufficiently early in the setup process of the FMU. This would require changes in many existing solver initialization routines. For example, an existing solver code might be just wrapped by an FMU-Co-Sim wrapper code. For example, our existing solvers will initialize with their own routines and typically create output directories alongside. If the information of the output location arrives sometimes later, the initialization code has to be taken apart and maintaining the stand-alone solver and the FMU-variant becomes more complicated. Therefore, knowing the output location before initialization of the solver helps creating FMUs from existing solver implementations.

[modelica-trac-importer]

Modified by andreas.junghanns on 6 Feb 2017 10:38 UTC

[modelica-trac-importer]

Comment by aviel on 13 Feb 2017 17:16 UTC Although it seems to be a tool-related issue that can be handled by introducing regular fixed parameters specific to the FMI exporting tool, I reschedule this as 2.1, since I do not see a need for introducing such new mechanisms in a maintenance release.

[modelica-trac-importer]

Comment by cbertsch on 1 Jun 2018 13:17 UTC A workaround is possible, see last comment. Could be covered by a future release if the demand is high enough.

[modelica-trac-importer]

Comment by Andreas Nicolai on 1 Jun 2018 15:29 UTC Indeed, it seems that among the FMI tool users very few are actually dealing with FMI-instance-specific outputs - most appear to rely on the client-master communication to pass on output data.

Maybe, when FMI becomes more widely accepted and scalability becomes an issue (say 1000nds of output variables that are dumped onto the master just for logging into result files) this may get some more attention.

Unfortunately, what I see in the field of building automation is, that due to lack of such a mechanism in the FMI standard, people write tool specific hard-coded output facilities which means that the user will be required to know each FMI specific handling and follow the (mostly undocumented) internal conventions. This in turn harms the "universal exchangeability" aspect of FMI - in fact, this does not (yet) exist in our engineering discipline.

[modelica-trac-importer]

Comment by andreas.junghanns on 1 Jun 2018 16:26 UTC May I suggest a different approach altogether? The issue here that FMUs have a fixed API. A master can ignore certain outputs (your case, but it applies to other variable types just the same), but can never add IO on user demand. This is due to the modelDescription.xml being fixed in the FMU.

If there was a capability flag dynamicIO and an optional C function getModelDescriptionXML(instanceParameters), the IO could be changed according to the instanceParameters dynamically. I know, this will need some changes in the state chart, but those are details.

However, this would allow a mechanism to adapt the IO from the outside. Andreas: Would that work for your use-case?

[modelica-trac-importer]

Comment by Andreas Nicolai on 1 Jun 2018 21:44 UTC Replying to [comment:12 Andreas Junghanns (QTronic)]:

The issue here that FMUs have a fixed API. A master can ignore certain outputs (your case, but it applies to other variable types just the same), but can never add IO on user demand. This is due to the modelDescription.xml being fixed in the FMU.

Hmm, I was aiming at outputs written natively by the FMU and without the master's knowledge. This is existing functionality of solvers that run in stand-alone mode. In my use case there is no need for the master to demand IO or modify this.

Let me give an example: an FMU generates per second some thousands output variables of telemetric data and has an optimized binary file format where the data is appended to or think of a videocam running inside the FMU where the video file is written on the fly. Clearly, this level of data would not be needed by the master - neither for exchange with other FMUs, nor for output by the master itself (it has no knowledge about the nature of the binary data it gets, nor the file format or whatever). Still, the FMU must know the location where to store its data/create its output files, and if the files are to be created during the initialization phase of the FMU (if, for whatever reason, it must exist from the start), than the FMU must know where to write it to. Hence, my suggestion to pass a writable location to the FMU.

Is this a scenario you were talking about with the dynamicIO capability flag?

[modelica-trac-importer]

Comment by cbertsch on 2 Jun 2018 12:37 UTC Couldn't the new binary data type (see FCP) be used for this purpose? The FMU could have paramters to configure which information to stream out.

[modelica-trac-importer]

Comment by andreas.junghanns on 2 Jun 2018 13:41 UTC For data storage during the simulation, you need not just the file name in a general case. You need at least:

• variable list selected for writing
• file name
• file format
• file format version
• file format options (separators, time/duration based, space options,...)
• time sampling options (dt, interrupt points,...)

I don't see how we can "simply" add a few string variable conventions. This seems too complicated.

To stream data out of the FMU, you can define a binary data type and then read that stream. However, this also means you have bake into the FMU what goes into the stream and format options etc. So this would not help much, except the stream goes via the FMU IO.

[modelica-trac-importer]

Comment by Andreas Nicolai on 4 Jun 2018 06:38 UTC While all these comments are valid, I think a major use-case aspect (see above) was overlooked.

There are many engineering simulation models out there (NOT Modelica!), which are already in a "command line" solver form and worthwhile being ported to FMI. These have existing and (over many years) established output/result writing functionality, with standardized output formats linked to analysis tool chains.

The use case is: let these solvers write their output files as they are so that existing users can continue with their workflows/tool chains. But tell the FMI where to write the data to.

I am not talking about newly developed software but enabling FMI for existing tools.

[modelica-trac-importer]

Comment by andreas.junghanns on 4 Jun 2018 06:59 UTC The most general solution I can think of is giving the FMU a directory where to leave the file behind. Not the file name, as that would include extension and we don't know that, but just a place that will be available for writing. Note: This is not the resourceLocation - as that will likely disappear after the simulation stopped.

[modelica-trac-importer]

Comment by Andreas Nicolai on 4 Jun 2018 08:16 UTC @Andreas Junghanns: Exactly! This is what I am aiming at. Let the master give the FMU a writable, preferably FMI instance-specific, location (only on platforms that support such a location, otherwise an empty string).

[modelica-trac-importer]

Modified by andreas.junghanns on 4 Jun 2018 09:28 UTC

[andreas-junghanns]

Web-design meeting: Since no real interest was seen during 7 years of this issue, we are closing this, including the PR for it.