simulator: Add energy modelling subsystem to OpenDC

This pull request adds a subsystem to OpenDC for modelling power components in datacenters, 
such as UPSes, PDUs and PSUs. 
These components also take into account electrical losses that occur in real-world scenarios.

- Add module for datacenter power components (UPS, PDU)
- Integrate power subsystem with compute subsystem (PSU)
- Model power loss in power components

**Breaking API Changes**

1. `SimBareMetalMachine.powerDraw` is replaced by `SimBareMetalMachine.psu.powerDraw`

5 files changed, 239 insertions, 20 deletions

diff --git a/opendc-simulator/opendc-simulator-compute/src/main/kotlin/org/opendc/simulator/compute/SimBareMetalMachine.kt b/opendc-simulator/opendc-simulator-compute/src/main/kotlin/org/opendc/simulator/compute/SimBareMetalMachine.kt
index 642873fd..7f416010 100644
--- a/opendc-simulator/opendc-simulator-compute/src/main/kotlin/org/opendc/simulator/compute/SimBareMetalMachine.kt
+++ b/opendc-simulator/opendc-simulator-compute/src/main/kotlin/org/opendc/simulator/compute/SimBareMetalMachine.kt
@@ -31,38 +31,35 @@ import org.opendc.simulator.resources.SimResourceInterpreter
  * A simulated bare-metal machine that is able to run a single workload.
  *
  * A [SimBareMetalMachine] is a stateful object and you should be careful when operating this object concurrently. For
- * example. The class expects only a single concurrent call to [run].
+ * example, the class expects only a single concurrent call to [run].
  *
  * @param interpreter The [SimResourceInterpreter] to drive the simulation.
  * @param model The machine model to simulate.
  * @param powerDriver The power driver to use.
+ * @param psu The power supply of the machine.
  * @param parent The parent simulation system.
  */
 public class SimBareMetalMachine(
     interpreter: SimResourceInterpreter,
     model: SimMachineModel,
     powerDriver: PowerDriver,
+    public val psu: SimPsu = SimPsu(500.0, mapOf(1.0 to 1.0)),
     parent: SimResourceSystem? = null,
 ) : SimAbstractMachine(interpreter, parent, model) {
+    /**
+     * The processing units of the machine.
+     */
     override val cpus: List<SimProcessingUnit> = model.cpus.map { cpu ->
         Cpu(SimResourceSource(cpu.frequency, interpreter, this@SimBareMetalMachine), cpu)
     }
 
-    /**
-     * Construct the [PowerDriver.Logic] for this machine.
-     */
-    private val powerDriver = powerDriver.createLogic(this, cpus)
-
-    /**
-     * The power draw of the machine.
-     */
-    public var powerDraw: Double = 0.0
-        private set
-
     override fun updateUsage(usage: Double) {
         super.updateUsage(usage)
+        psu.update()
+    }
 
-        powerDraw = powerDriver.computePower()
+    init {
+        psu.connect(powerDriver.createLogic(this, cpus))
     }
 
     /**
diff --git a/opendc-simulator/opendc-simulator-compute/src/main/kotlin/org/opendc/simulator/compute/SimPsu.kt b/opendc-simulator/opendc-simulator-compute/src/main/kotlin/org/opendc/simulator/compute/SimPsu.kt
new file mode 100644
index 00000000..4ddad1c9
--- /dev/null
+++ b/opendc-simulator/opendc-simulator-compute/src/main/kotlin/org/opendc/simulator/compute/SimPsu.kt
@@ -0,0 +1,115 @@
+/*
+ * Copyright (c) 2021 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.simulator.compute
+
+import org.opendc.simulator.compute.power.PowerDriver
+import org.opendc.simulator.power.SimPowerInlet
+import org.opendc.simulator.resources.SimResourceCommand
+import org.opendc.simulator.resources.SimResourceConsumer
+import org.opendc.simulator.resources.SimResourceContext
+import org.opendc.simulator.resources.SimResourceEvent
+import java.util.*
+
+/**
+ * A power supply of a [SimBareMetalMachine].
+ *
+ * @param ratedOutputPower The rated output power of the PSU.
+ * @param energyEfficiency The energy efficiency of the PSU for various power draws.
+ */
+public class SimPsu(
+    private val ratedOutputPower: Double,
+    energyEfficiency: Map<Double, Double>,
+) : SimPowerInlet() {
+    /**
+     * The power draw of the machine at this instant.
+     */
+    public val powerDraw: Double
+        get() = _powerDraw
+    private var _powerDraw = 0.0
+
+    /**
+     * The energy efficiency of the PSU at various power draws.
+     */
+    private val energyEfficiency = TreeMap(energyEfficiency)
+
+    /**
+     * The consumer context.
+     */
+    private var _ctx: SimResourceContext? = null
+
+    /**
+     * The driver that is connected to the PSU.
+     */
+    private var _driver: PowerDriver.Logic? = null
+
+    init {
+        require(energyEfficiency.isNotEmpty()) { "Must specify at least one entry for energy efficiency of PSU" }
+    }
+
+    /**
+     * Update the power draw of the PSU.
+     */
+    public fun update() {
+        _ctx?.interrupt()
+    }
+
+    /**
+     * Connect the specified [PowerDriver.Logic] to this PSU.
+     */
+    public fun connect(driver: PowerDriver.Logic) {
+        check(_driver == null) { "PSU already connected" }
+        _driver = driver
+        update()
+    }
+
+    override fun createConsumer(): SimResourceConsumer = object : SimResourceConsumer {
+        override fun onNext(ctx: SimResourceContext): SimResourceCommand {
+            val powerDraw = computePowerDraw(_driver?.computePower() ?: 0.0)
+
+            return if (powerDraw > 0.0)
+                SimResourceCommand.Consume(Double.POSITIVE_INFINITY, powerDraw, Long.MAX_VALUE)
+            else
+                SimResourceCommand.Idle()
+        }
+
+        override fun onEvent(ctx: SimResourceContext, event: SimResourceEvent) {
+            when (event) {
+                SimResourceEvent.Start -> _ctx = ctx
+                SimResourceEvent.Run -> _powerDraw = ctx.speed
+                SimResourceEvent.Exit -> _ctx = null
+                else -> {}
+            }
+        }
+    }
+
+    /**
+     * Compute the power draw of the PSU including the power loss.
+     */
+    private fun computePowerDraw(load: Double): Double {
+        val loadPercentage = (load / ratedOutputPower).coerceIn(0.0, 1.0)
+        val efficiency = energyEfficiency.ceilingEntry(loadPercentage)?.value ?: 1.0
+        return load / efficiency
+    }
+
+    override fun toString(): String = "SimPsu[draw=$_powerDraw]"
+}
diff --git a/opendc-simulator/opendc-simulator-compute/src/main/kotlin/org/opendc/simulator/compute/power/PowerDriver.kt b/opendc-simulator/opendc-simulator-compute/src/main/kotlin/org/opendc/simulator/compute/power/PowerDriver.kt
index a1a2b911..1a46dd4a 100644
--- a/opendc-simulator/opendc-simulator-compute/src/main/kotlin/org/opendc/simulator/compute/power/PowerDriver.kt
+++ b/opendc-simulator/opendc-simulator-compute/src/main/kotlin/org/opendc/simulator/compute/power/PowerDriver.kt
@@ -26,22 +26,22 @@ import org.opendc.simulator.compute.SimMachine
 import org.opendc.simulator.compute.SimProcessingUnit
 
 /**
- * A [PowerDriver] is responsible for switching the processor to the correct frequency.
+ * A [PowerDriver] is responsible for tracking the power usage for a component of the machine.
  */
 public interface PowerDriver {
     /**
-     * Create the scaling logic for the specified [machine]
+     * Create the driver logic for the specified [machine].
      */
     public fun createLogic(machine: SimMachine, cpus: List<SimProcessingUnit>): Logic
 
     /**
-     * The logic of the scaling driver.
+     * The logic of the power driver.
      */
     public interface Logic {
         /**
-         * Compute the power consumption of the processor.
+         * Compute the power consumption of the component.
          *
-         * @return The power consumption of the processor in W.
+         * @return The power consumption of the component in W.
          */
         public fun computePower(): Double
     }
diff --git a/opendc-simulator/opendc-simulator-compute/src/test/kotlin/org/opendc/simulator/compute/SimMachineTest.kt b/opendc-simulator/opendc-simulator-compute/src/test/kotlin/org/opendc/simulator/compute/SimMachineTest.kt
index 0c686aa0..b9cfb06b 100644
--- a/opendc-simulator/opendc-simulator-compute/src/test/kotlin/org/opendc/simulator/compute/SimMachineTest.kt
+++ b/opendc-simulator/opendc-simulator-compute/src/test/kotlin/org/opendc/simulator/compute/SimMachineTest.kt
@@ -40,6 +40,7 @@ import org.opendc.simulator.compute.util.SimWorkloadLifecycle
 import org.opendc.simulator.compute.workload.SimFlopsWorkload
 import org.opendc.simulator.compute.workload.SimWorkload
 import org.opendc.simulator.core.runBlockingSimulation
+import org.opendc.simulator.power.SimPowerSource
 import org.opendc.simulator.resources.SimResourceInterpreter
 import org.opendc.simulator.resources.consumer.SimWorkConsumer
 
@@ -142,16 +143,20 @@ class SimMachineTest {
 
     @Test
     fun testPower() = runBlockingSimulation {
+        val interpreter = SimResourceInterpreter(coroutineContext, clock)
         val machine = SimBareMetalMachine(
-            SimResourceInterpreter(coroutineContext, clock),
+            interpreter,
             machineModel,
             SimplePowerDriver(LinearPowerModel(100.0, 50.0))
         )
+        val source = SimPowerSource(interpreter, capacity = 1000.0)
+        source.connect(machine.psu)
 
         try {
             coroutineScope {
                 launch { machine.run(SimFlopsWorkload(2_000, utilization = 1.0)) }
-                assertEquals(100.0, machine.powerDraw)
+                assertEquals(100.0, machine.psu.powerDraw)
+                assertEquals(100.0, source.powerDraw)
             }
         } finally {
             machine.close()
diff --git a/opendc-simulator/opendc-simulator-compute/src/test/kotlin/org/opendc/simulator/compute/SimPsuTest.kt b/opendc-simulator/opendc-simulator-compute/src/test/kotlin/org/opendc/simulator/compute/SimPsuTest.kt
new file mode 100644
index 00000000..e0ebdb73
--- /dev/null
+++ b/opendc-simulator/opendc-simulator-compute/src/test/kotlin/org/opendc/simulator/compute/SimPsuTest.kt
@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2021 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.simulator.compute
+
+import io.mockk.every
+import io.mockk.mockk
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
+import org.opendc.simulator.compute.power.PowerDriver
+import org.opendc.simulator.core.runBlockingSimulation
+import org.opendc.simulator.power.SimPowerSource
+import org.opendc.simulator.resources.SimResourceInterpreter
+
+/**
+ * Test suite for [SimPsu]
+ */
+internal class SimPsuTest {
+
+    @Test
+    fun testInvalidInput() {
+        assertThrows<IllegalArgumentException> { SimPsu(1.0, emptyMap()) }
+    }
+
+    @Test
+    fun testDoubleConnect() {
+        val psu = SimPsu(1.0, mapOf(0.0 to 1.0))
+        val cpuLogic = mockk<PowerDriver.Logic>()
+        psu.connect(cpuLogic)
+        assertThrows<IllegalStateException> { psu.connect(mockk()) }
+    }
+
+    @Test
+    fun testPsuIdle() = runBlockingSimulation {
+        val ratedOutputPower = 240.0
+        val energyEfficiency = mapOf(0.0 to 1.0)
+
+        val interpreter = SimResourceInterpreter(coroutineContext, clock)
+        val source = SimPowerSource(interpreter, capacity = ratedOutputPower)
+
+        val cpuLogic = mockk<PowerDriver.Logic>()
+        every { cpuLogic.computePower() } returns 0.0
+
+        val psu = SimPsu(ratedOutputPower, energyEfficiency)
+        psu.connect(cpuLogic)
+        source.connect(psu)
+
+        assertEquals(0.0, source.powerDraw, 0.01)
+    }
+
+    @Test
+    fun testPsuPowerLoss() = runBlockingSimulation {
+        val ratedOutputPower = 240.0
+        // Efficiency of 80 Plus Titanium PSU
+        val energyEfficiency = sortedMapOf(
+            0.3 to 0.9,
+            0.7 to 0.92,
+            1.0 to 0.94,
+        )
+
+        val interpreter = SimResourceInterpreter(coroutineContext, clock)
+        val source = SimPowerSource(interpreter, capacity = ratedOutputPower)
+
+        val cpuLogic = mockk<PowerDriver.Logic>()
+        every { cpuLogic.computePower() } returnsMany listOf(50.0, 100.0, 150.0, 200.0)
+
+        val psu = SimPsu(ratedOutputPower, energyEfficiency)
+        psu.connect(cpuLogic)
+        source.connect(psu)
+
+        assertEquals(55.55, source.powerDraw, 0.01)
+
+        psu.update()
+        assertEquals(108.695, source.powerDraw, 0.01)
+
+        psu.update()
+        assertEquals(163.043, source.powerDraw, 0.01)
+
+        psu.update()
+        assertEquals(212.765, source.powerDraw, 0.01)
+    }
+}