refactor(#18): Redesign core simulation API

This change contains the redesign of the core simulation API and
provides a cleaner interface for developing simulation models for the
users.

8 files changed, 527 insertions, 0 deletions

diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt
new file mode 100644
index 00000000..199e1701
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt
@@ -0,0 +1,64 @@
+package com.atlarge.opendc.simulator
+
+/**
+ * A bootstrapping interface for a conceptual model that is a logical representation of some system of entities,
+ * relationships and processes, as a basis for simulations.
+ *
+ * @param M The shape of the model that is bootstrapped.
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Bootstrap<M> {
+	/**
+	 * Bootstrap a model `M` for a kernel in the given context.
+	 *
+	 * @param context The context to bootstrap to model in.
+	 * @return The initialised model for the simulation.
+	 */
+	fun bootstrap(context: Context<M>): M
+
+	/**
+	 * A context for the bootstrap of some model type `M` that allows the model to register the entities of the model to
+	 * the simulation kernel.
+	 *
+	 * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+	 */
+	interface Context<out M> {
+		/**
+		 * Register the given entity to the simulation kernel.
+		 *
+		 * @param entity The entity to register.
+		 * @return `true` if the entity had not yet been registered, `false` otherwise.
+		 */
+		fun register(entity: Entity<*, M>): Boolean
+
+		/**
+		 * Deregister the given entity from the simulation kernel.
+		 *
+		 * @param entity The entity to deregister.
+		 * @return `true` if the entity had not yet been unregistered, `false` otherwise.
+		 */
+		fun deregister(entity: Entity<*, M>): Boolean
+
+		/**
+		 * Schedule a message for processing by a [Context].
+		 *
+		 * @param message The message to schedule.
+		 * @param destination The destination of the message.
+		 * @param sender The sender of the message.
+		 * @param delay The amount of time to wait before processing the message.
+		 */
+		fun schedule(message: Any, destination: Entity<*, *>, sender: Entity<*, *>? = null, delay: Duration = 0)
+	}
+
+	companion object {
+		/**
+		 * Create a [Bootstrap] procedure using the given block to produce a bootstrap for a model of type `M`.
+		 *
+		 * @param block The block to produce the bootstrap.
+		 * @return The bootstrap procedure that has been built.
+		 */
+		fun <M> create(block: (Context<M>) -> M): Bootstrap<M> = object : Bootstrap<M> {
+			override fun bootstrap(context: Context<M>) = block(context)
+		}
+	}
+}
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Context.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Context.kt
new file mode 100644
index 00000000..c4e906dd
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Context.kt
@@ -0,0 +1,184 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2017 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 com.atlarge.opendc.simulator
+
+import java.util.Queue
+
+/**
+ * This interface provides a context for simulation of [Entity] instances, by defining the environment in which the
+ * simulation is run and provides means of communicating with other entities in the environment and control its own
+ * behaviour.
+ *
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Context<S, out M> {
+	/**
+	 * The model of simulation in which the entity exists.
+	 */
+	val model: M
+
+	/**
+	 * The current point in simulation time.
+	 */
+	val time: Instant
+
+	/**
+	 * The duration between the current point in simulation time and the last point in simulation time where the
+	 * [Entity] has done some work. This means the `run()` co-routine has been resumed.
+	 */
+	val delta: Duration
+
+	/**
+	 * The observable state of the entity bound to this scope.
+	 */
+	var state: S
+
+	/**
+	 * The observable state of an [Entity] in simulation, which is provided by the simulation context.
+	 */
+	val <E : Entity<S, *>, S> E.state: S
+
+	/**
+	 * Interrupt an [Entity] process in simulation.
+	 *
+	 * If an [Entity] process has been suspended, the suspending call will throw an [Interrupt] object as a result of
+	 * this call.
+	 * Make sure the [Entity] process actually has error handling in place, so it won't take down the whole [Entity]
+	 * process as result of the interrupt.
+	 */
+	suspend fun Entity<*, *>.interrupt()
+
+	/**
+	 * Suspend the [Context] of the [Entity] in simulation for the given duration of simulation time before resuming
+	 * execution and drop all messages that are received during this period.
+	 *
+	 * A call to this method will not make the [Context] sleep for the actual duration of time, but instead suspend
+	 * the process until the no more messages at an earlier point in time have to be processed.
+	 *
+	 * @param duration The duration of simulation time to hold before resuming execution.
+	 */
+	suspend fun hold(duration: Duration)
+
+	/**
+	 * Suspend the [Context] of the [Entity] in simulation for the given duration of simulation time before resuming
+	 * execution and push all messages that are received during this period to the given queue.
+	 *
+	 * A call to this method will not make the [Context] sleep for the actual duration of time, but instead suspend
+	 * the process until the no more messages at an earlier point in time have to be processed.
+	 *
+	 * @param duration The duration of simulation time to wait before resuming execution.
+	 * @param queue The mutable queue to push the messages to.
+	 */
+	suspend fun hold(duration: Duration, queue: Queue<Any>)
+
+	/**
+	 * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is
+	 * empty. The execution is resumed after the head of the mailbox is removed after which the message [Envelope] is
+	 * transformed through `transform` to return the transformed result.
+	 *
+	 * @param transform The block to transform the message with in an envelope context, providing access to the sender
+	 * 					of the message.
+	 * @return The transformed message.
+	 */
+	suspend fun <T> receive(transform: suspend Envelope<*>.(Any) -> T): T
+
+	/**
+	 * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is
+	 * empty. The execution is either resumed after the head of the mailbox is removed after which the message
+	 * [Envelope] is transformed through `transform` to return the transformed result or the timeout has been reached.
+	 *
+	 * @param timeout The duration to wait before resuming execution.
+	 * @param transform The block to transform the message with in an envelope context, providing access to the sender
+	 * 					of the message.
+	 * @return The processed message or `null` if the timeout was reached.
+	 */
+	suspend fun <T> receive(timeout: Duration, transform: suspend Envelope<*>.(Any) -> T): T?
+
+	/**
+	 * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is
+	 * empty. The execution is resumed after the head of the mailbox is removed and returned.
+	 *
+	 * @return The received message.
+	 */
+	suspend fun receive(): Any = receive { it }
+
+	/**
+	 * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is
+	 * empty. The execution is either resumed after the head of the mailbox is removed and returned or when the timeout
+	 * has been reached.
+	 *
+	 * @return The received message or `null` if the timeout was reached.
+	 */
+	suspend fun receive(timeout: Duration): Any? = receive(timeout) { it }
+
+	/**
+	 * Send the given message to the specified entity, without providing any guarantees about the actual delivery of
+	 * the message.
+	 *
+	 * @param msg The message to send.
+	 * @param delay The amount of time to wait before the message should be received by the entity.
+	 */
+	suspend fun Entity<*, *>.send(msg: Any, delay: Duration = 0)
+
+	/**
+	 * Send the given message to the specified entity, without providing any guarantees about the actual delivery of
+	 * the message.
+	 *
+	 * @param msg The message to send.
+	 * @param sender The sender of the message.
+	 * @param delay The amount of time to wait before the message should be received by the entity.
+	 */
+	suspend fun Entity<*, *>.send(msg: Any, sender: Entity<*, *>, delay: Duration = 0)
+}
+
+/**
+ * The message envelope that is sent to an [Entity], also containing the metadata of the message.
+ *
+ * @param T The shape of the message inside the envelope.
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Envelope<out T: Any> {
+	/**
+	 * The message in this envelope.
+	 */
+	val message: T
+
+	/**
+	 * The sender of the message.
+	 */
+	val sender: Entity<*, *>?
+
+	/**
+	 * The destination of the message.
+	 */
+	val destination: Entity<*, *>
+}
+
+/**
+ * An [Interrupt] message is sent to a [Entity] process in order to interrupt its suspended state.
+ *
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+object Interrupt: Throwable("The entity process has been interrupted by another entity")
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Entity.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Entity.kt
new file mode 100644
index 00000000..800f2f1d
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Entity.kt
@@ -0,0 +1,44 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2017 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 com.atlarge.opendc.simulator
+
+/**
+ * An entity in some model `M`.
+ *
+ * <p>A [Entity] directly contains its immutable properties that remain unchanged during simulation.
+ *
+ * <p>In addition, other entities in simulation have direct, immutable access to the observable state of this entity.
+ *
+ * @param S The shape of the observable state of this entity, which is directly accessible by other components within
+ * a simulation.
+ * @param M The shape of the model in which the entity exists.
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Entity<out S, in M> {
+	/**
+	 * The initial state of the entity.
+	 */
+	val initialState: S
+}
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Process.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Process.kt
new file mode 100644
index 00000000..30280657
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Process.kt
@@ -0,0 +1,27 @@
+package com.atlarge.opendc.simulator
+
+/**
+ * A process is dynamic entity within a simulation, that interacts with the model environment by the interchange of
+ * messages.
+ *
+ * @param S The shape of the observable state of the process.
+ * @param M The shape of the model in which the process exists.
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Process<S, in M>: Entity<S, M> {
+	/**
+	 * This method is invoked to start the simulation a process.
+	 *
+	 * This method is assumed to be running during a simulation, but should hand back control to the simulator at
+	 * some point by suspending the process. This allows other processes to do work at the current point in time of the
+	 * simulation.
+	 * Suspending the process can be achieved by calling suspending method in the context:
+	 * 	- [Context.hold]	- Hold for `n` units of time before resuming execution.
+	 * 	- [Context.receive]	- Wait for a message to be received in the mailbox of the [Entity] before resuming
+	 * 	execution.
+	 *
+	 * If this method exits early, before the simulation has finished, the entity is assumed to be shutdown and its
+	 * simulation will not run any further.
+	 */
+	suspend fun Context<S, M>.run()
+}
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Time.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Time.kt
new file mode 100644
index 00000000..64e3cb80
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Time.kt
@@ -0,0 +1,35 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2017 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 com.atlarge.opendc.simulator
+
+/**
+ * An instantaneous point on the time-line, used to record event time-stamps in a simulation.
+ */
+typealias Instant = Long
+
+/**
+ * A time interval which represents the amount of elapsed time between two events.
+ */
+typealias Duration = Long
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt
new file mode 100644
index 00000000..3eee0f67
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt
@@ -0,0 +1,79 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2017 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 com.atlarge.opendc.simulator.kernel
+
+import com.atlarge.opendc.simulator.Bootstrap
+import com.atlarge.opendc.simulator.Instant
+import com.atlarge.opendc.simulator.Entity
+
+/**
+ * A message based discrete event simulation kernel.
+ *
+ * The kernel is created by bootstrapping some model `M` (see [Bootstrap]) to simulate and controls the simulation by
+ * allowing the user to step over cycles in the simulation and inspect the internal state using [Entity.state].
+ *
+ * A kernel should provide additionally a [KernelFactory] to create new kernel instances given a certain model
+ * [Bootstrap].
+ *
+ * @param M The shape of the model over which the simulation runs.
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Kernel<out M> {
+	/**
+	 * The model in which the simulation runs.
+	 */
+	val model: M
+
+	/**
+	 * The simulation time.
+	 */
+	var time: Instant
+
+	/**
+	 * The observable state of an [Entity] in simulation, which is provided by the simulation context.
+	 */
+	val <E : Entity<S, *>, S> E.state: S
+
+	/**
+	 * Step through one cycle in the simulation. This method will process all events in a single tick, update the
+	 * internal clock and then return the control to the user.
+	 */
+	fun step()
+
+	/**
+	 * Run a simulation over the specified model.
+	 * This method will step through multiple cycles in the simulation until no more message exist in the queue.
+	 */
+	fun run()
+
+	/**
+	 * Run a simulation over the specified model, stepping through cycles until the specified clock tick has
+	 * occurred. The control is then handed back to the user.
+	 *
+	 * @param until The point in simulation time at which the simulation should be paused and the control is handed
+	 * 				back to the user.
+	 */
+	fun run(until: Instant)
+}
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/KernelFactory.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/KernelFactory.kt
new file mode 100644
index 00000000..93667eb8
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/KernelFactory.kt
@@ -0,0 +1,42 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2017 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 com.atlarge.opendc.simulator.kernel
+
+import com.atlarge.opendc.simulator.Bootstrap
+
+/**
+ * A factory for bootstrapping simulation [Kernel] instances.
+ *
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface KernelFactory {
+	/**
+	 * Create a simulation over the given model facilitated by this simulation kernel.
+	 *
+	 * @param bootstrap The bootstrap procedure to bootstrap the simulation with.
+	 * @return A [Kernel] instance to control the simulation.
+	 */
+	fun <M> create(bootstrap: Bootstrap<M>): Kernel<M>
+}
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt
new file mode 100644
index 00000000..88b606fd
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt
@@ -0,0 +1,52 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2017 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 com.atlarge.opendc.simulator.platform
+
+import com.atlarge.opendc.simulator.kernel.KernelFactory
+import com.atlarge.opendc.simulator.Duration
+
+/**
+ * A blueprint for a reproducible simulation in a pre-defined setting.
+ *
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Experiment<out T> {
+	/**
+	 * Run the experiment on the specified kernel implementation.
+	 *
+	 * @param factory The factory to create the simulation kernel with.
+	 * @return The result of the experiment.
+	 */
+	fun run(factory: KernelFactory): T
+
+	/**
+	 * Run the experiment on the specified kernel implementation.
+	 *
+	 * @param factory The factory to create the simulation kernel with.
+	 * @param timeout The maximum duration of the experiment before returning to the caller.
+	 * @return The result of the experiment or `null`.
+	 */
+	fun run(factory: KernelFactory, timeout: Duration): T?
+}