Enh/77 fmu tools page

CHANGELOG.md

@@ -7,6 +7,7 @@ The changelog format is based on [Keep a Changelog](https://keepachangelog.com/e
 
 ### Changed
 
+* Add README page for Examples dir, add generated FMUs for each example (given FMI tools page requirements for Examples), and update the files generated by mlfmu codegen (add for pyspark example)
 * Generation of modelDescription.xml file to correctly generate tags for each output with 1-indexed indexes and InitialUnknowns tags
 * Generation of modelDescription.xml adds the variables (inputs, parameters and outputs) in the orderer of their valueReference. This is for the indexing to work correctly
 

examples/README.md

@@ -0,0 +1,16 @@
+# Examples
+
+This folder contains a couple of example files to use for testing the MLFMU tools and some FMUs that have been generated using this tool.
+Each folder is set up to contain at least:
+
+* `config`: the `.onnx` and `interface.json` files, which you can use to test the `mlfmu` commands with
+* `generated_fmu`: binary FMU files, to serve as examples, as generated when running `mlfmu build` for the config files
+* `<FmuName>`: files for the FMU as generated when running `mlfmu codegen`
+
+The FMUs in this folder have been validated using [FMU_check].
+
+For further documentation of the `mlfmu` tool, see [README.md](../README.md) or the [docs] on GitHub pages.
+
+<!-- Markdown link & img dfn's -->
+[FMU_check]: https://fmu-check.herokuapp.com/
+[docs]: https://dnv-opensource.github.io/mlfmu/

examples/wind_generator/WindGenerator/modelDescription.xml

@@ -1,4 +1,4 @@
-<fmiModelDescription fmiVersion="2.0" modelName="WindGenerator" guid="@FMU_UUID@" version="0.0.1" generationDateAndTime="2024-03-12T14:06:00+00:00" variableNamingConvention="structured" generationTool="MLFMU 0.1.6" description="A Machine Learning based FMU that outputs a synthetic time series of wind.">
+<fmiModelDescription fmiVersion="2.0" modelName="WindGenerator" guid="@FMU_UUID@" version="0.0.1" generationDateAndTime="2024-12-19T13:46:28+00:00" variableNamingConvention="structured" generationTool="MLFMU 1.0.2" description="A Machine Learning based FMU that outputs a synthetic time series of wind.">
 	<CoSimulation modelIdentifier="WindGenerator" canHandleVariableCommunicationStepSize="true" />
 	<ModelVariables>
 		<ScalarVariable name="speedNoise" valueReference="0" causality="input" description="Noise to be added to the change in wind speed" variability="continuous">
@@ -7,23 +7,27 @@
 		<ScalarVariable name="directionNoise" valueReference="1" causality="input" description="Noise to be added to the change in wind direction" variability="continuous">
 			<Real start="0" />
 		</ScalarVariable>
-		<ScalarVariable name="initialWindSpeed" valueReference="4" causality="parameter" description="" variability="fixed">
-			<Real start="10.0" />
-		</ScalarVariable>
-		<ScalarVariable name="initialWindDirection" valueReference="5" causality="parameter" description="" variability="fixed">
-			<Real start="180.0" />
-		</ScalarVariable>
 		<ScalarVariable name="windSpeed" valueReference="2" causality="output" description="The speed of the wind" variability="continuous">
 			<Real />
 		</ScalarVariable>
 		<ScalarVariable name="windDirection" valueReference="3" causality="output" description="The direction of the wind" variability="continuous">
 			<Real />
 		</ScalarVariable>
+		<ScalarVariable name="initialWindSpeed" valueReference="4" causality="parameter" description="" variability="fixed">
+			<Real start="10.0" />
+		</ScalarVariable>
+		<ScalarVariable name="initialWindDirection" valueReference="5" causality="parameter" description="" variability="fixed">
+			<Real start="180.0" />
+		</ScalarVariable>
 	</ModelVariables>
 	<ModelStructure>
 		<Outputs>
-			<Unknown index="2" />
 			<Unknown index="3" />
+			<Unknown index="4" />
 		</Outputs>
+		<InitialUnknowns>
+			<Unknown index="3" />
+			<Unknown index="4" />
+		</InitialUnknowns>
 	</ModelStructure>
 </fmiModelDescription>

examples/wind_generator/WindGenerator/sources/fmu.cpp

@@ -5,12 +5,41 @@
 #include <onnxFmu.hpp>
 
 
+/**
+ * \class WindGenerator
+ * \brief A class representing an WindGenerator FMU.
+ *
+ * This class is derived from the OnnxFmu class and provides functionality specific to the WindGenerator FMU.
+ */
 class WindGenerator : public OnnxFmu {
     public :
-        WindGenerator(cppfmu::FMIString fmuResourceLocation) : OnnxFmu(fmuResourceLocation) {} private :
-};
+        /**
+         * \brief Constructs a new WindGenerator object.
+         *
+         * \param fmuResourceLocation The location of the resources of the FMU.
+         */
+        WindGenerator(cppfmu::FMIString fmuResourceLocation) : OnnxFmu(fmuResourceLocation) {}
 
+    private :
+        // Add private members and functions here
+};
 
+/**
+ * \brief Instantiate a `slave` instance of the FMU.
+ *
+ * \param instanceName The name of the FMU instance.
+ * \param fmuGUID The GUID of the FMU.
+ * \param fmuResourceLocation The location of the FMU resource.
+ * \param mimeType The MIME type of the FMU.
+ * \param timeout The timeout value for the instantiation process.
+ * \param visible Flag indicating whether the FMU should be visible.
+ * \param interactive Flag indicating whether the FMU should be interactive.
+ * \param memory The memory to be used for the FMU instance.
+ * \param logger The logger to be used for logging messages.
+ * \returns A unique pointer to the instantiated slave instance.
+ *
+ * \throws std::runtime_error if the FMU GUID does not match.
+ */
 cppfmu::UniquePtr<cppfmu::SlaveInstance> CppfmuInstantiateSlave(
     cppfmu::FMIString /*instanceName*/, cppfmu::FMIString fmuGUID, cppfmu::FMIString fmuResourceLocation,
     cppfmu::FMIString /*mimeType*/, cppfmu::FMIReal /*timeout*/, cppfmu::FMIBoolean /*visible*/,

examples/wind_to_power/WindToPower/modelDescription.xml

@@ -1,19 +1,22 @@
-<fmiModelDescription fmiVersion="2.0" modelName="WindToPower" guid="@FMU_UUID@" version="0.0.1" generationDateAndTime="2024-03-12T14:06:31+00:00" variableNamingConvention="structured" generationTool="MLFMU 0.1.6" description="A Machine Learning based FMU that outputs the estimated power output of a windmill given the wind speed and direction.">
+<fmiModelDescription fmiVersion="2.0" modelName="WindToPower" guid="@FMU_UUID@" version="0.0.1" generationDateAndTime="2024-12-19T13:47:01+00:00" variableNamingConvention="structured" generationTool="MLFMU 1.0.2" description="A Machine Learning based FMU that outputs the estimated power output of a wind turbine given the wind speed and direction.">
 	<CoSimulation modelIdentifier="WindToPower" canHandleVariableCommunicationStepSize="true" />
 	<ModelVariables>
-		<ScalarVariable name="windSpeed" valueReference="0" causality="input" description="Noise to be added to the change in wind speed" variability="continuous">
+		<ScalarVariable name="windSpeed" valueReference="0" causality="input" description="The speed of the wind" variability="continuous">
 			<Real start="0" />
 		</ScalarVariable>
-		<ScalarVariable name="windDirection" valueReference="1" causality="input" description="Noise to be added to the change in wind direction" variability="continuous">
+		<ScalarVariable name="windDirection" valueReference="1" causality="input" description="The direction of the wind" variability="continuous">
 			<Real start="0" />
 		</ScalarVariable>
-		<ScalarVariable name="power" valueReference="2" causality="output" description="The estimated windmill power output" variability="continuous">
+		<ScalarVariable name="power" valueReference="2" causality="output" description="The estimated wind turbine power output" variability="continuous">
 			<Real />
 		</ScalarVariable>
 	</ModelVariables>
 	<ModelStructure>
 		<Outputs>
-			<Unknown index="2" />
+			<Unknown index="3" />
 		</Outputs>
+		<InitialUnknowns>
+			<Unknown index="3" />
+		</InitialUnknowns>
 	</ModelStructure>
 </fmiModelDescription>

examples/wind_to_power/WindToPower/sources/fmu.cpp

@@ -5,12 +5,41 @@
 #include <onnxFmu.hpp>
 
 
+/**
+ * \class WindToPower
+ * \brief A class representing an WindToPower FMU.
+ *
+ * This class is derived from the OnnxFmu class and provides functionality specific to the WindToPower FMU.
+ */
 class WindToPower : public OnnxFmu {
     public :
-        WindToPower(cppfmu::FMIString fmuResourceLocation) : OnnxFmu(fmuResourceLocation) {} private :
-};
+        /**
+         * \brief Constructs a new WindToPower object.
+         *
+         * \param fmuResourceLocation The location of the resources of the FMU.
+         */
+        WindToPower(cppfmu::FMIString fmuResourceLocation) : OnnxFmu(fmuResourceLocation) {}
 
+    private :
+        // Add private members and functions here
+};
 
+/**
+ * \brief Instantiate a `slave` instance of the FMU.
+ *
+ * \param instanceName The name of the FMU instance.
+ * \param fmuGUID The GUID of the FMU.
+ * \param fmuResourceLocation The location of the FMU resource.
+ * \param mimeType The MIME type of the FMU.
+ * \param timeout The timeout value for the instantiation process.
+ * \param visible Flag indicating whether the FMU should be visible.
+ * \param interactive Flag indicating whether the FMU should be interactive.
+ * \param memory The memory to be used for the FMU instance.
+ * \param logger The logger to be used for logging messages.
+ * \returns A unique pointer to the instantiated slave instance.
+ *
+ * \throws std::runtime_error if the FMU GUID does not match.
+ */
 cppfmu::UniquePtr<cppfmu::SlaveInstance> CppfmuInstantiateSlave(
     cppfmu::FMIString /*instanceName*/, cppfmu::FMIString fmuGUID, cppfmu::FMIString fmuResourceLocation,
     cppfmu::FMIString /*mimeType*/, cppfmu::FMIReal /*timeout*/, cppfmu::FMIBoolean /*visible*/,

examples/wind_to_power_pyspark/MLFMU_RF_Regressor/modelDescription.xml

@@ -0,0 +1,28 @@
+<fmiModelDescription fmiVersion="2.0" modelName="MLFMU_RF_Regressor" guid="@FMU_UUID@" version="0.0.1" generationDateAndTime="2024-12-19T13:47:29+00:00" variableNamingConvention="structured" generationTool="MLFMU 1.0.2" description="A Random Forest Regressor based FMU">
+	<CoSimulation modelIdentifier="MLFMU_RF_Regressor" canHandleVariableCommunicationStepSize="true" />
+	<ModelVariables>
+		<ScalarVariable name="features[0]" valueReference="0" causality="input" description="Inputs with four features: month, hour, wind_speed, wind_direction" variability="continuous">
+			<Real start="0" />
+		</ScalarVariable>
+		<ScalarVariable name="features[1]" valueReference="1" causality="input" description="Inputs with four features: month, hour, wind_speed, wind_direction" variability="continuous">
+			<Real start="0" />
+		</ScalarVariable>
+		<ScalarVariable name="features[2]" valueReference="2" causality="input" description="Inputs with four features: month, hour, wind_speed, wind_direction" variability="continuous">
+			<Real start="0" />
+		</ScalarVariable>
+		<ScalarVariable name="features[3]" valueReference="3" causality="input" description="Inputs with four features: month, hour, wind_speed, wind_direction" variability="continuous">
+			<Real start="0" />
+		</ScalarVariable>
+		<ScalarVariable name="prediction" valueReference="4" causality="output" description="The prediction generated by ML model" variability="continuous">
+			<Real />
+		</ScalarVariable>
+	</ModelVariables>
+	<ModelStructure>
+		<Outputs>
+			<Unknown index="5" />
+		</Outputs>
+		<InitialUnknowns>
+			<Unknown index="5" />
+		</InitialUnknowns>
+	</ModelStructure>
+</fmiModelDescription>

examples/wind_to_power_pyspark/MLFMU_RF_Regressor/sources/fmu.cpp

@@ -0,0 +1,52 @@
+#include "fmu-uuid.h"
+#include "model_definitions.h"
+
+#include <cppfmu_cs.hpp>
+#include <onnxFmu.hpp>
+
+
+/**
+ * \class MLFMU_RF_Regressor
+ * \brief A class representing an MLFMU_RF_Regressor FMU.
+ *
+ * This class is derived from the OnnxFmu class and provides functionality specific to the MLFMU_RF_Regressor FMU.
+ */
+class MLFMU_RF_Regressor : public OnnxFmu {
+    public :
+        /**
+         * \brief Constructs a new MLFMU_RF_Regressor object.
+         *
+         * \param fmuResourceLocation The location of the resources of the FMU.
+         */
+        MLFMU_RF_Regressor(cppfmu::FMIString fmuResourceLocation) : OnnxFmu(fmuResourceLocation) {}
+
+    private :
+        // Add private members and functions here
+};
+
+/**
+ * \brief Instantiate a `slave` instance of the FMU.
+ *
+ * \param instanceName The name of the FMU instance.
+ * \param fmuGUID The GUID of the FMU.
+ * \param fmuResourceLocation The location of the FMU resource.
+ * \param mimeType The MIME type of the FMU.
+ * \param timeout The timeout value for the instantiation process.
+ * \param visible Flag indicating whether the FMU should be visible.
+ * \param interactive Flag indicating whether the FMU should be interactive.
+ * \param memory The memory to be used for the FMU instance.
+ * \param logger The logger to be used for logging messages.
+ * \returns A unique pointer to the instantiated slave instance.
+ *
+ * \throws std::runtime_error if the FMU GUID does not match.
+ */
+cppfmu::UniquePtr<cppfmu::SlaveInstance> CppfmuInstantiateSlave(
+    cppfmu::FMIString /*instanceName*/, cppfmu::FMIString fmuGUID, cppfmu::FMIString fmuResourceLocation,
+    cppfmu::FMIString /*mimeType*/, cppfmu::FMIReal /*timeout*/, cppfmu::FMIBoolean /*visible*/,
+    cppfmu::FMIBoolean /*interactive*/, cppfmu::Memory memory, cppfmu::Logger /*logger*/)
+{
+    if (std::strcmp(fmuGUID, FMU_UUID) != 0) {
+        throw std::runtime_error("FMU GUID mismatch");
+    }
+    return cppfmu::AllocateUnique<MLFMU_RF_Regressor>(memory, fmuResourceLocation);
+}

examples/wind_to_power_pyspark/MLFMU_RF_Regressor/sources/model_definitions.h

@@ -0,0 +1,22 @@
+#define NUM_FMU_VARIABLES 5
+
+#define NUM_ONNX_INPUTS 4
+#define NUM_ONNX_FMU_INPUTS 4
+#define NUM_ONNX_OUTPUTS 1
+#define NUM_ONNX_FMU_OUTPUTS 1
+#define NUM_ONNX_STATES 0
+#define NUM_ONNX_STATES_OUTPUTS 0
+#define NUM_ONNX_STATE_INIT 0
+
+#define ONNX_INPUT_VALUE_REFERENCES 0, 0, 1, 1, 2, 2, 3, 3
+#define ONNX_OUTPUT_VALUE_REFERENCES 0, 4
+#define ONNX_STATE_OUTPUT_INDEXES
+#define ONNX_STATE_INIT_VALUE_REFERENCES
+
+#define ONNX_USE_TIME_INPUT false
+
+#define ONNX_INPUT_NAME "features"
+#define ONNX_OUTPUT_NAME "prediction"
+#define ONNX_STATE_NAME ""
+#define ONNX_TIME_INPUT_NAME ""
+#define ONNX_FILENAME L"rf_model.onnx"