M3SA - Multi-Meta-Model Simulation Analyzer (#251)

* (feat) demo files are now ignored

* integrating m3sa changes with opendc

* gitignore ignores demo

* m3sa linked, tested, works 🎉🎆

* linting & checks fully pass

* m3sa documentation (re...)added

* package.json added, a potentail solution for Build Docker Images workflow

* (fix) opendc-m3sa renamed to opendc-experiments-m3sa

* (feat) Model is now a dataclass

* (fix) package and package-lock reverted as before the PR, now they mirror the opendc master branch

* (fix) Experiments renamed to experiment

* branch updated with changes from master branch

* trying to fix the build docker image failed workflow

* trying to fix the build docker image failed workflow

* All simulation are now run with a single CPU and single MemoryUnit. multi CPUs are combined into one. This is for performance and explainability. (#255) (#37)

Co-authored-by: Dante Niewenhuis <d.niewenhuis@hotmail.com>

* All simulation are now run with a single CPU and single MemoryUnit. multi CPUs are combined into one. This is for performance and explainability. (#255) (#38)

Co-authored-by: Dante Niewenhuis <d.niewenhuis@hotmail.com>

* All simulation are now run with a single CPU and single MemoryUnit. multi CPUs are combined into one. This is for performance and explainability. (#255) (#39)

Co-authored-by: Dante Niewenhuis <d.niewenhuis@hotmail.com>

* [TEMP](feat) m3saCli decoupled from experimentCli

* spotless and minor refactoring

* (feat)[TEMP] decoupling m3sa from experiment

* spotless applied

* documentation resolved

* requirements.txt added

* path to M3SA is now provided as a parameter to M3SACLI

* spotless applied

* (fix) python environment variables solved, output analysis folder solved

* documentation changed and matching the master branch doc

* package-lock reverted

* package-lock reverted

---------

Co-authored-by: Dante Niewenhuis <d.niewenhuis@hotmail.com>

4 files changed, 236 insertions, 0 deletions

diff --git a/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/M3saAnalyzer.kt b/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/M3saAnalyzer.kt
new file mode 100644
index 00000000..6b8f8422
--- /dev/null
+++ b/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/M3saAnalyzer.kt
@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2024 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import kotlin.io.path.Path
+
+/**
+ * This constant variable should be changed depending on the root folder that is being run.
+ * PATH_TO_PYTHON_MAIN should point to the main python file, ran when the analysis starts.
+ */
+
+public val ANALYSIS_SCRIPTS_DIRECTORY: String = "./opendc-experiments/opendc-experiments-m3sa/src/main/python"
+public val ABSOLUTE_SCRIPT_PATH: String =
+    Path("$ANALYSIS_SCRIPTS_DIRECTORY/main.py").toAbsolutePath().normalize().toString()
+public val SCRIPT_LANGUAGE: String = Path("$ANALYSIS_SCRIPTS_DIRECTORY/venv/bin/python3").toAbsolutePath().normalize().toString()
+
+public fun m3saAnalyze(
+    outputFolderPath: String,
+    m3saSetupPath: String,
+) {
+    val process =
+        ProcessBuilder(
+            SCRIPT_LANGUAGE,
+            ABSOLUTE_SCRIPT_PATH,
+            outputFolderPath,
+            m3saSetupPath,
+        ).directory(Path(ANALYSIS_SCRIPTS_DIRECTORY).toFile())
+            .start()
+
+    val exitCode = process.waitFor()
+    if (exitCode == 0) {
+        println("[M3SA says] M3SA operation(s) completed successfully.")
+    } else {
+        val errors = process.errorStream.bufferedReader().readText()
+        println("[M3SA says] Exit code $exitCode; Error(s): $errors")
+    }
+}
diff --git a/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/runner/M3SACli.kt b/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/runner/M3SACli.kt
new file mode 100644
index 00000000..43597ff5
--- /dev/null
+++ b/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/runner/M3SACli.kt
@@ -0,0 +1,85 @@
+/*
+ * Copyright (c) 2022 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+@file:JvmName("M3SACli")
+
+package org.opendc.experiments.base.runner
+
+import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.parameters.options.default
+import com.github.ajalt.clikt.parameters.options.defaultLazy
+import com.github.ajalt.clikt.parameters.options.option
+import com.github.ajalt.clikt.parameters.types.file
+import com.github.ajalt.clikt.parameters.types.int
+import m3saAnalyze
+import org.opendc.experiments.base.scenario.getExperiment
+import org.opendc.experiments.m3sa.scenario.getOutputFolder
+import java.io.File
+
+/**
+ * Main entrypoint of the application.
+ */
+public fun main(args: Array<String>): Unit = M3SACommand().main(args)
+
+/**
+ * Represents the command for the Scenario experiments.
+ */
+internal class M3SACommand : CliktCommand(name = "experiment") {
+    /**
+     * The path to the environment directory.
+     */
+    private val scenarioPath by option("--experiment-path", help = "path to experiment file")
+        .file(canBeDir = false, canBeFile = true)
+        .defaultLazy { File("resources/experiment.json") }
+
+    /**
+     * The number of threads to use for parallelism.
+     */
+    private val parallelism by option("-p", "--parallelism", help = "number of worker threads")
+        .int()
+        .default(Runtime.getRuntime().availableProcessors() - 1)
+
+    private val m3saPath by option("-m", "--m3sa-setup-path", help = "path to m3sa setup file")
+        .file(canBeDir = false, canBeFile = true)
+        .defaultLazy { File("") }
+
+    override fun run() {
+        println("The provided m3saPath is $m3saPath")
+
+        val experiment = getExperiment(scenarioPath)
+        runExperiment(experiment, parallelism)
+
+        if (m3saPath.toString().isNotEmpty()) {
+            m3saAnalyze(
+                outputFolderPath = getOutputFolder(scenarioPath),
+                m3saSetupPath = m3saPath.toString(),
+            )
+        } else {
+            println(
+                "\n" +
+                    "===================================================\n" +
+                    "|M3SA path is not provided. Skipping M3SA analysis.|\n" +
+                    "===================================================",
+            )
+        }
+    }
+}
diff --git a/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/runner/M3SARunner.kt b/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/runner/M3SARunner.kt
new file mode 100644
index 00000000..9a61ad17
--- /dev/null
+++ b/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/runner/M3SARunner.kt
@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2024 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+@file:JvmName("M3saCliKt")
+
+package org.opendc.experiments.base.runner
+
+import org.opendc.experiments.base.scenario.Scenario
+import java.util.concurrent.ForkJoinPool
+
+/**
+ * Run scenario when no pool is available for parallel execution
+ *
+ * @param experiment The scenarios to run
+ * @param parallelism The number of scenarios that can be run in parallel
+ */
+public fun runExperiment(
+    experiment: List<Scenario>,
+    parallelism: Int,
+) {
+    val ansiReset = "\u001B[0m"
+    val ansiGreen = "\u001B[32m"
+    val ansiBlue = "\u001B[34m"
+
+    setupOutputFolderStructure(experiment[0].outputFolder)
+
+    for (scenario in experiment) {
+        val pool = ForkJoinPool(parallelism)
+        println(
+            "\n\n$ansiGreen================================================================================$ansiReset",
+        )
+        println("$ansiBlue Running scenario: ${scenario.name} $ansiReset")
+        println("$ansiGreen================================================================================$ansiReset")
+        runScenario(
+            scenario,
+            pool,
+        )
+    }
+}
diff --git a/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/scenario/M3SAFactories.kt b/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/scenario/M3SAFactories.kt
new file mode 100644
index 00000000..a4df40e1
--- /dev/null
+++ b/opendc-experiments/opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/scenario/M3SAFactories.kt
@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2024 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.opendc.experiments.m3sa.scenario
+
+import org.opendc.experiments.base.scenario.ExperimentReader
+import java.io.File
+
+private val experimentReader = ExperimentReader()
+
+/**
+ * Returns a list of Scenarios from a given file path (input).
+ *
+ * @param filePath The path to the file containing the scenario specifications.
+ * @return A list of Scenarios.
+ */
+public fun getOutputFolder(file: File): String {
+    return experimentReader.read(file).outputFolder + "/outputs"
+}