Documentation update (#261)

* Updated a lot of documentation, added a new get-started tutorial. * Applied Spotless * Applied Spotless Java * Added bitbrains workload to site
atlarge-research · Nov 5, 2024 · 0f835d5 · 0f835d5
1 parent f3e578a
commit 0f835d5
Show file tree

Hide file tree

Showing 46 changed files with 752 additions and 326 deletions.
diff --git a/...pute/opendc-compute-carbon/src/main/kotlin/org/opendc/compute/carbon/CarbonTraceLoader.kt b/...pute/opendc-compute-carbon/src/main/kotlin/org/opendc/compute/carbon/CarbonTraceLoader.kt
@@ -22,7 +22,7 @@
 
 package org.opendc.compute.carbon
 
-import org.opendc.simulator.compute.power.CarbonFragmentNew
+import org.opendc.simulator.compute.power.CarbonFragment
 import org.opendc.trace.Trace
 import org.opendc.trace.conv.CARBON_INTENSITY_TIMESTAMP
 import org.opendc.trace.conv.CARBON_INTENSITY_VALUE
@@ -41,14 +41,14 @@ public class CarbonTraceLoader {
     /**
      * The cache of workloads.
      */
-    private val cache = ConcurrentHashMap<String, SoftReference<List<CarbonFragmentNew>>>()
+    private val cache = ConcurrentHashMap<String, SoftReference<List<CarbonFragment>>>()
 
     private val builder = CarbonFragmentNewBuilder()
 
     /**
      * Read the metadata into a workload.
      */
-    private fun parseCarbon(trace: Trace): List<CarbonFragmentNew> {
+    private fun parseCarbon(trace: Trace): List<CarbonFragment> {
         val reader = checkNotNull(trace.getTable(TABLE_CARBON_INTENSITIES)).newReader()
 
         val startTimeCol = reader.resolve(CARBON_INTENSITY_TIMESTAMP)
@@ -77,7 +77,7 @@ public class CarbonTraceLoader {
     /**
      * Load the trace with the specified [name] and [format].
      */
-    public fun get(pathToFile: File): List<CarbonFragmentNew> {
+    public fun get(pathToFile: File): List<CarbonFragment> {
         val trace = Trace.open(pathToFile, "carbon")
 
         return parseCarbon(trace)
@@ -97,7 +97,7 @@ public class CarbonTraceLoader {
         /**
          * The total load of the trace.
          */
-        public val fragments: MutableList<CarbonFragmentNew> = mutableListOf()
+        public val fragments: MutableList<CarbonFragment> = mutableListOf()
 
         /**
          * Add a fragment to the trace.
@@ -110,7 +110,11 @@ public class CarbonTraceLoader {
             carbonIntensity: Double,
         ) {
             fragments.add(
-                CarbonFragmentNew(startTime.toEpochMilli(), Long.MAX_VALUE, carbonIntensity),
+                CarbonFragment(
+                    startTime.toEpochMilli(),
+                    Long.MAX_VALUE,
+                    carbonIntensity,
+                ),
             )
         }
 

diff --git a/...pute/opendc-compute-carbon/src/main/kotlin/org/opendc/compute/carbon/CarbonTraceReader.kt b/...pute/opendc-compute-carbon/src/main/kotlin/org/opendc/compute/carbon/CarbonTraceReader.kt
@@ -24,14 +24,14 @@
 
 package org.opendc.compute.carbon
 
-import org.opendc.simulator.compute.power.CarbonFragmentNew
+import org.opendc.simulator.compute.power.CarbonFragment
 import java.io.File
 import javax.management.InvalidAttributeValueException
 
 /**
  * Construct a workload from a trace.
  */
-public fun getCarbonFragments(pathToFile: String?): List<CarbonFragmentNew>? {
+public fun getCarbonFragments(pathToFile: String?): List<CarbonFragment>? {
     if (pathToFile == null) {
         return null
     }
@@ -42,7 +42,7 @@ public fun getCarbonFragments(pathToFile: String?): List<CarbonFragmentNew>? {
 /**
  * Construct a workload from a trace.
  */
-public fun getCarbonFragments(file: File): List<CarbonFragmentNew> {
+public fun getCarbonFragments(file: File): List<CarbonFragment> {
     if (!file.exists()) {
         throw InvalidAttributeValueException("The carbon trace cannot be found")
     }

diff --git a/opendc-experiments/opendc-experiments-base/build.gradle.kts b/opendc-experiments/opendc-experiments-base/build.gradle.kts
@@ -52,16 +52,16 @@ dependencies {
 val createScenarioApp by tasks.creating(CreateStartScripts::class) {
     dependsOn(tasks.jar)
 
-    applicationName = "OpenDCScenarioRunner"
-    mainClass.set("org.opendc.experiments.base.runner.ScenarioCli")
+    applicationName = "OpenDCExperimentRunner"
+    mainClass.set("org.opendc.experiments.base.runner.ExperimentCli")
     classpath = tasks.jar.get().outputs.files + configurations["runtimeClasspath"]
     outputDir = project.buildDir.resolve("scripts")
 }
 
 // Create custom Scenario distribution
 distributions {
     main {
-        distributionBaseName.set("OpenDCScenarioRunner")
+        distributionBaseName.set("OpenDCExperimentRunner")
 
         contents {
             from("README.md")

diff --git a/...ents/base/scenario/ExperimentFactories.kt → ...ts/base/experiment/ExperimentFactories.kt b/...ents/base/scenario/ExperimentFactories.kt → ...ts/base/experiment/ExperimentFactories.kt
@@ -20,10 +20,10 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario
+package org.opendc.experiments.base.experiment
 
-import org.opendc.experiments.base.scenario.specs.ExperimentSpec
-import org.opendc.experiments.base.scenario.specs.ScenarioSpec
+import org.opendc.experiments.base.experiment.specs.ExperimentSpec
+import org.opendc.experiments.base.experiment.specs.ScenarioSpec
 import java.io.File
 
 private val experimentReader = ExperimentReader()

diff --git a/...riments/base/scenario/ExperimentReader.kt → ...ments/base/experiment/ExperimentReader.kt b/...riments/base/scenario/ExperimentReader.kt → ...ments/base/experiment/ExperimentReader.kt
@@ -20,13 +20,13 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario
+package org.opendc.experiments.base.experiment
 
 import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.decodeFromStream
 import org.opendc.compute.simulator.telemetry.parquet.ComputeExportConfig
-import org.opendc.experiments.base.scenario.specs.ExperimentSpec
+import org.opendc.experiments.base.experiment.specs.ExperimentSpec
 import java.io.File
 import java.io.InputStream
 import java.nio.file.Path

diff --git a/...riments/base/scenario/ExperimentWriter.kt → ...ments/base/experiment/ExperimentWriter.kt b/...riments/base/scenario/ExperimentWriter.kt → ...ments/base/experiment/ExperimentWriter.kt
@@ -20,11 +20,11 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario
+package org.opendc.experiments.base.experiment
 
 import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.Json
-import org.opendc.experiments.base.scenario.specs.ScenarioSpec
+import org.opendc.experiments.base.experiment.specs.ScenarioSpec
 import java.io.File
 
 /**

diff --git a/...ndc/experiments/base/scenario/Scenario.kt → ...c/experiments/base/experiment/Scenario.kt b/...ndc/experiments/base/scenario/Scenario.kt → ...c/experiments/base/experiment/Scenario.kt
@@ -20,15 +20,15 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario
+package org.opendc.experiments.base.experiment
 
 import org.opendc.compute.simulator.telemetry.parquet.ComputeExportConfig
-import org.opendc.experiments.base.scenario.specs.AllocationPolicySpec
-import org.opendc.experiments.base.scenario.specs.CheckpointModelSpec
-import org.opendc.experiments.base.scenario.specs.ExportModelSpec
-import org.opendc.experiments.base.scenario.specs.FailureModelSpec
-import org.opendc.experiments.base.scenario.specs.ScenarioTopologySpec
-import org.opendc.experiments.base.scenario.specs.WorkloadSpec
+import org.opendc.experiments.base.experiment.specs.AllocationPolicySpec
+import org.opendc.experiments.base.experiment.specs.CheckpointModelSpec
+import org.opendc.experiments.base.experiment.specs.ExportModelSpec
+import org.opendc.experiments.base.experiment.specs.FailureModelSpec
+import org.opendc.experiments.base.experiment.specs.ScenarioTopologySpec
+import org.opendc.experiments.base.experiment.specs.WorkloadSpec
 
 /**
  * A data class representing a scenario for a set of experiments.

diff --git a/...se/scenario/specs/AllocationPolicySpec.kt → .../experiment/specs/AllocationPolicySpec.kt b/...se/scenario/specs/AllocationPolicySpec.kt → .../experiment/specs/AllocationPolicySpec.kt
@@ -20,7 +20,7 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario.specs
+package org.opendc.experiments.base.experiment.specs
 
 import kotlinx.serialization.Serializable
 import org.opendc.compute.simulator.scheduler.ComputeSchedulerEnum

diff --git a/...ase/scenario/specs/CheckpointModelSpec.kt → ...e/experiment/specs/CheckpointModelSpec.kt b/...ase/scenario/specs/CheckpointModelSpec.kt → ...e/experiment/specs/CheckpointModelSpec.kt
@@ -20,7 +20,7 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario.specs
+package org.opendc.experiments.base.experiment.specs
 
 import kotlinx.serialization.Serializable
 

diff --git a/...nts/base/scenario/specs/ExperimentSpec.kt → ...s/base/experiment/specs/ExperimentSpec.kt b/...nts/base/scenario/specs/ExperimentSpec.kt → ...s/base/experiment/specs/ExperimentSpec.kt
@@ -20,7 +20,7 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario.specs
+package org.opendc.experiments.base.experiment.specs
 
 import kotlinx.serialization.Serializable
 import org.opendc.common.logger.infoNewLine
@@ -50,14 +50,14 @@ public data class ExperimentSpec(
     val outputFolder: String = "output",
     val initialSeed: Int = 0,
     val runs: Int = 1,
+    val exportModels: Set<ExportModelSpec> = setOf(ExportModelSpec()),
+    val computeExportConfig: ComputeExportConfig = ComputeExportConfig.ALL_COLUMNS,
+    val maxNumFailures: Set<Int> = setOf(10),
     val topologies: Set<ScenarioTopologySpec>,
     val workloads: Set<WorkloadSpec>,
     val allocationPolicies: Set<AllocationPolicySpec> = setOf(AllocationPolicySpec()),
-    val exportModels: Set<ExportModelSpec> = setOf(ExportModelSpec()),
     val failureModels: Set<FailureModelSpec?> = setOf(null),
     val checkpointModels: Set<CheckpointModelSpec?> = setOf(null),
-    val computeExportConfig: ComputeExportConfig = ComputeExportConfig.ALL_COLUMNS,
-    val maxNumFailures: Set<Int> = setOf(10),
 ) {
     init {
         require(runs > 0) { "The number of runs should always be positive" }

diff --git a/...ts/base/scenario/specs/ExportModelSpec.kt → .../base/experiment/specs/ExportModelSpec.kt b/...ts/base/scenario/specs/ExportModelSpec.kt → .../base/experiment/specs/ExportModelSpec.kt
@@ -20,7 +20,7 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario.specs
+package org.opendc.experiments.base.experiment.specs
 
 import kotlinx.serialization.Serializable
 

diff --git a/...s/base/scenario/specs/FailureModelSpec.kt → ...base/experiment/specs/FailureModelSpec.kt b/...s/base/scenario/specs/FailureModelSpec.kt → ...base/experiment/specs/FailureModelSpec.kt
@@ -20,7 +20,7 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario.specs
+package org.opendc.experiments.base.experiment.specs
 
 /*
  * Copyright (c) 2024 AtLarge Research

diff --git a/...nts/base/scenario/specs/PowerModelSpec.kt → ...s/base/experiment/specs/PowerModelSpec.kt b/...nts/base/scenario/specs/PowerModelSpec.kt → ...s/base/experiment/specs/PowerModelSpec.kt
@@ -20,7 +20,7 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario.specs
+package org.opendc.experiments.base.experiment.specs
 
 import kotlinx.serialization.Serializable
 

diff --git a/...ments/base/scenario/specs/ScenarioSpec.kt → ...nts/base/experiment/specs/ScenarioSpec.kt b/...ments/base/scenario/specs/ScenarioSpec.kt → ...nts/base/experiment/specs/ScenarioSpec.kt
@@ -20,7 +20,7 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario.specs
+package org.opendc.experiments.base.experiment.specs
 
 import kotlinx.serialization.Serializable
 import org.opendc.compute.simulator.telemetry.parquet.ComputeExportConfig

diff --git a/...se/scenario/specs/ScenarioTopologySpec.kt → .../experiment/specs/ScenarioTopologySpec.kt b/...se/scenario/specs/ScenarioTopologySpec.kt → .../experiment/specs/ScenarioTopologySpec.kt
@@ -20,7 +20,7 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario.specs
+package org.opendc.experiments.base.experiment.specs
 
 import kotlinx.serialization.Serializable
 import java.io.File

diff --git a/...ments/base/scenario/specs/WorkloadSpec.kt → ...nts/base/experiment/specs/WorkloadSpec.kt b/...ments/base/scenario/specs/WorkloadSpec.kt → ...nts/base/experiment/specs/WorkloadSpec.kt
@@ -20,7 +20,7 @@
  * SOFTWARE.
  */
 
-package org.opendc.experiments.base.scenario.specs
+package org.opendc.experiments.base.experiment.specs
 
 import kotlinx.serialization.Serializable
 import org.opendc.compute.workload.ComputeWorkload

diff --git a/...endc-experiments-base/src/main/kotlin/org/opendc/experiments/base/runner/ExperimentCli.kt b/...endc-experiments-base/src/main/kotlin/org/opendc/experiments/base/runner/ExperimentCli.kt
@@ -30,7 +30,7 @@ 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 org.opendc.experiments.base.scenario.getExperiment
+import org.opendc.experiments.base.experiment.getExperiment
 import java.io.File
 
 /**

diff --git a/...c-experiments-base/src/main/kotlin/org/opendc/experiments/base/runner/ExperimentRunner.kt b/...c-experiments-base/src/main/kotlin/org/opendc/experiments/base/runner/ExperimentRunner.kt
@@ -22,7 +22,7 @@
 
 package org.opendc.experiments.base.runner
 
-import org.opendc.experiments.base.scenario.Scenario
+import org.opendc.experiments.base.experiment.Scenario
 import java.util.concurrent.ForkJoinPool
 
 /**

diff --git a/...c-experiments-base/src/main/kotlin/org/opendc/experiments/base/runner/ScenarioReplayer.kt b/...c-experiments-base/src/main/kotlin/org/opendc/experiments/base/runner/ScenarioReplayer.kt
@@ -35,8 +35,8 @@ import org.opendc.compute.simulator.TaskWatcher
 import org.opendc.compute.simulator.service.ComputeService
 import org.opendc.compute.simulator.service.ServiceTask
 import org.opendc.compute.workload.Task
-import org.opendc.experiments.base.scenario.specs.FailureModelSpec
-import org.opendc.experiments.base.scenario.specs.createFailureModel
+import org.opendc.experiments.base.experiment.specs.FailureModelSpec
+import org.opendc.experiments.base.experiment.specs.createFailureModel
 import java.time.InstantSource
 import java.util.Random
 import kotlin.coroutines.coroutineContext

diff --git a/...ndc-experiments-base/src/main/kotlin/org/opendc/experiments/base/runner/ScenarioRunner.kt b/...ndc-experiments-base/src/main/kotlin/org/opendc/experiments/base/runner/ScenarioRunner.kt
@@ -33,8 +33,8 @@ import org.opendc.compute.simulator.service.ComputeService
 import org.opendc.compute.simulator.telemetry.parquet.ParquetComputeMonitor
 import org.opendc.compute.topology.clusterTopology
 import org.opendc.compute.workload.ComputeWorkloadLoader
-import org.opendc.experiments.base.scenario.Scenario
-import org.opendc.experiments.base.scenario.specs.getWorkloadType
+import org.opendc.experiments.base.experiment.Scenario
+import org.opendc.experiments.base.experiment.specs.getWorkloadType
 import org.opendc.simulator.kotlin.runSimulation
 import java.io.File
 import java.time.Duration

diff --git a/...c-experiments-base/src/test/kotlin/org/opendc/experiments/base/ScenarioIntegrationTest.kt b/...c-experiments-base/src/test/kotlin/org/opendc/experiments/base/ScenarioIntegrationTest.kt
@@ -45,8 +45,8 @@ import org.opendc.compute.workload.ComputeWorkloadLoader
 import org.opendc.compute.workload.Task
 import org.opendc.compute.workload.sampleByLoad
 import org.opendc.compute.workload.trace
+import org.opendc.experiments.base.experiment.specs.TraceBasedFailureModelSpec
 import org.opendc.experiments.base.runner.replay
-import org.opendc.experiments.base.scenario.specs.TraceBasedFailureModelSpec
 import org.opendc.simulator.kotlin.runSimulation
 import java.io.File
 import java.util.Random

diff --git a/...nts/opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/runner/M3SACli.kt b/...nts/opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/runner/M3SACli.kt
@@ -30,8 +30,8 @@ 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 org.opendc.experiments.base.experiment.getExperiment
 import org.opendc.experiments.base.runner.runExperiment
-import org.opendc.experiments.base.scenario.getExperiment
 import org.opendc.experiments.m3sa.m3saAnalyze
 import org.opendc.experiments.m3sa.scenario.getOutputFolder
 import java.io.File

diff --git a/.../opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/runner/M3SARunner.kt b/.../opendc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/runner/M3SARunner.kt
@@ -24,9 +24,9 @@
 
 package org.opendc.experiments.m3sa.runner
 
+import org.opendc.experiments.base.experiment.Scenario
 import org.opendc.experiments.base.runner.runScenario
 import org.opendc.experiments.base.runner.setupOutputFolderStructure
-import org.opendc.experiments.base.scenario.Scenario
 import java.util.concurrent.ForkJoinPool
 
 /**

diff --git a/...dc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/scenario/M3SAFactories.kt b/...dc-experiments-m3sa/src/main/kotlin/org/opendc/experiments/m3sa/scenario/M3SAFactories.kt
@@ -22,7 +22,7 @@
 
 package org.opendc.experiments.m3sa.scenario
 
-import org.opendc.experiments.base.scenario.ExperimentReader
+import org.opendc.experiments.base.experiment.ExperimentReader
 import java.io.File
 
 private val experimentReader = ExperimentReader()

diff --git a/...ator/compute/power/CarbonFragmentNew.java → ...mulator/compute/power/CarbonFragment.java b/...ator/compute/power/CarbonFragmentNew.java → ...mulator/compute/power/CarbonFragment.java
@@ -22,12 +22,16 @@
 
 package org.opendc.simulator.compute.power;
 
-public class CarbonFragmentNew {
-    private long endTime;
+/**
+ * An object holding the carbon intensity during a specific time frame.
+ * Used by {@link CarbonModel}.
+ */
+public class CarbonFragment {
     private long startTime;
+    private long endTime;
     private double carbonIntensity;
 
-    public CarbonFragmentNew(long startTime, long endTime, double carbonIntensity) {
+    public CarbonFragment(long startTime, long endTime, double carbonIntensity) {
         this.setStartTime(startTime);
         this.setEndTime(endTime);
         this.setCarbonIntensity(carbonIntensity);