kalasim is licensed under MIT License.
kalasim started off as a blunt rewrite of salabim. We are deeply thankful for its permissive licence that enabled setting up kalasim. A great starting point was in particular the wonderful article salabim: discrete event simulation and animation in Python.
salabims excellent documentation and wonderful examples made this project possible after all. kalasim reimplements all core APIs of salabim in a more typesafe API while also providing better test coverage, real-time capabilities and (arguably) more modern built-in support for visualization.
simmer is a process-oriented and trajectory-based Discrete-Event Simulation (DES) package for R.
+It centres around the concept of a trajectory that defines a component lifecycle. To enable scale it is built on top of Rcpp (C++ backend for R).
+We have adopted several examples and documentation bits from simmer, and are deeply grateful to the simmer developers for providing such a great and well maintained tool. simmer has also been a great source of inspiration to implement in particular the monitoring and visualization API of kalasim.
SimJulia is a combined continuous time / discrete event process oriented simulation framework written in Julia inspired by the Simula library DISCO and the Python library SimPy.
+We have adopted several examples and documentation bits from SimJulia, and are deeply grateful its developers for providing such a great and well maintained tool.
SimPy is a process-based discrete-event simulation framework based on standard Python. Processes in SimPy are defined by Python generator functions. SimPy also provides various types of shared resources to model limited capacity congestion points (like servers, checkout counters and tunnels).
We have adopted several examples and documentation bits from SimPy, and are deeply grateful its developers for providing such a great and well maintained tool.
DSOL3 which is an open source, Java based suite of Java classes for continuous and discrete event simulation
+kalasim is built on top of some great libraries. It was derived as merger of ideas, implementation and documentation from the following projects:
kalasim provides a machine-readable log-format for all basics in a simulation.Visualization
+Inspirations
+Holger Brandl holds a Ph.D. degree in machine learning and has developed new concepts in the field of computational linguistics. More recently he has co-authored publications in high-ranking journals such as Nature and Science.
+To stay in sync with what's happening in tech, he's developing open-source tools, methods and algorithms for bioinformatics, high-performance computing and data science. He's passionate about machine learning, AI, analytics, elegant APIs and data visualisation. His professional scope mainly centers around systems biology and industrial manufacturing.
+ + + + + + +In simulation a clear distinction is made between real time and simulation time. With real time we refer to the wall-clock time. It represents the execution time of the experiment. The simulation time is an attribute of the simulator.
+To support use cases where a simulation may drive a demonstration or system check, the kalasim API allows to run a simulation at a defined clock speed. Such real-time simulations may be necessary
import org.kalasim.*
+import kotlin.time.Duration.Companion.seconds
+
+val timeBefore = System.currentTimeMillis()
+
+createSimulation {
+ enableComponentLogger()
+
+ // enable real-time clock synchronization
+ ClockSync(tickDuration = 1.seconds)
+
+ run(10)
+}
+
+println("time passed ${System.currentTimeMillis() - timeBefore})")
+To enable clock synchronization, we need to add a ClockSync to our simulation. We need to define what one tick in simulation time corresponds to in wall time. In the example, one tick equals to one second wall time. This is configured with the parameter tickDuration. It defines the duration of a simulation tick in wall clock coordinates. It can be created with Duration.ofSeconds(1), Duration.ofMinutes(10) and so on.
ClockSync also provides settings for more advanced uses-cases
speedUp to run a simulation faster (speedUp > 1) or slower (speedUp < 1) than realtime. It defaults to 1, that is no speed-up will be applied.syncsPerTick defines how often a clock synchronization should happen. Per default it synchronizes once per tick (i.e. an 1-increment of simulation time).It may happen that a simulation is too complex to run at a defined clock. In such a situation, it (i.e. Environment.run()) will throw a ClockOverloadException if the user has specified a maximum delay maxDelay parameter between simulation and wall clock coordinates.
Even if kalasim tries to provide a simplistic, efficient, declarative approach to define a simulation, it may come along with computational demands simulation. To allow introspection into time-complexity of the underlying computations, the user may want to enable the built-in env.tickMetrics monitor to analyze how much time is spent per time unit (aka tick). This monitor can be enabled by calling enableTickMetrics() when configuring the simulation.
import org.kalasim.*
+import org.kalasim.plot.letsplot.display
+
+createSimulation {
+ enableTickMetrics()
+
+ object : Component() {
+ override fun process() = sequence {
+ while(true) {
+ // create some artificial non-linear compute load
+ if(nowTT.value < 7)
+ Thread.sleep((nowTT.value * 100).toLong())
+ else {
+ Thread.sleep(100)
+ }
+
+ hold(1.minutes)
+ }
+ }
+ }
+
+ run(10.hours)
+
+ tickMetrics.display().show()
+}
+There are multiple ways to improve the performance of a simulation.
+AssertMode: The assertion mode determines which internal consistency checks are being performed. The mode can be set to Full (Slowest), Light (default) or Off (Fastest). Depending on simulation logic and complexity, this will improve performance by ~20%.To further fine-tune and optimize simulation performance and to reveal bottlenecks, a JVM profiler (such as yourkit or the built-in profiler of Intellij IDEA Ultimate) can be used. Both call-counts and spent-time analysis have been proven useful here.
+For some use-cases, simulations may run for a very long simulation and wall time. To prevent internal metrics gathering from consuming all available memory, it needs to be disabled or at least configured carefully. This can be achieved, but either disabling timelines and monitors manually on a per-entity basis, or by setting a sensible default policy via Environment.entityTrackingDefaults
For each entity type a corresponding tracking-policy TrackingConfig can be provisioned along with an entity matcher to narrow down its scope. A tracking-policy allows to change
There are different default implementations, but the user can also implement and register custom tracking-configurations.
+//import org.kalasim.*
+import org.kalasim.misc.*
+import kotlin.time.Duration.Companion.hours
+import kotlin.time.Duration.Companion.minutes
+
+
+class Driver : Resource(trackingConfig = ResourceTrackingConfig(trackUtilization = false))
+class TrafficLight : State<String>("red", trackingConfig = StateTrackingConfig(logCreation = false))
+
+class Car : Component(
+ trackingConfig = ComponentTrackingConfig(logInteractionEvents = false)
+) {
+
+ val trafficLight = get<TrafficLight>()
+ val driver = get<Driver>()
+
+ override fun process() = sequence {
+ request(driver) {
+ hold(30.minutes, description = "driving")
+
+ wait(trafficLight, "green")
+ }
+ }
+}
+
+createSimulation {
+ enableComponentLogger()
+
+ // in addition or alternatively we can also change the environment defaults
+ entityTrackingDefaults.DefaultComponentConfig =
+ ComponentTrackingConfig(logStateChangeEvents = false)
+
+ // create simulation entities
+ dependency { TrafficLight() }
+ dependency { Driver() }
+
+ Car()
+}.run(5.hours)
+Note
+Tracking configuration policies defaults must be set before instantiating simulation entities to be used
+To disable all metrics and to minimize internal event logging, the user can run env.entityTrackingDefaults.disableAll()
The same mechanism applies also fine-tune the internal event logging. By disabling some - not-needed for production - events, simulation performance can be improved significantly.
+kalasim does not include a default mechanism to serialize and deserialize simulations yet. However, it seems that with xstream that Environment can be saved including its current simulation state across all included entities. It can be restored from the xml snapshot and continued with run().
We have not succeeded to do the same with gson yet. Also, some experiments with kotlinx.serialization were not that successful.
+The simulation engine provides different levels of internal consistency checks. As these are partially computationally expensive these can be be/disabled. There are 3 modes
+OFF - Productive mode, where asserts that may impact performance are disabled.LIGHT - Disables compute-intensive asserts. This will have a minimal to moderate performance impact on simulations.FULL - Full introspection, this will have a measurable performance impact on simulations. E.g. it will validate that passive components are not scheduled, and queued components have unique names.Switching off asserts, will typically optimize performance by another ~20% (depending on simulation logic).
+ + + + + + +A core aspect when building simulations is to understand, define and modulate the inherent system dynamics. To build a correct simulation, the designer/developer must carefully analyze how states progress over time.
+To facilitate this process, kalasim offers various means to analyze data created by a simulation
See chapter about monitors.
+See chapter about event logging.
+See chapter about visualization.
+The state transition of a component provide value insight into its behavior. This is facilitated by lifecycle statistics ComponentLifecycleRecord that summarize a component's states history.
These data can also be transformed easily into a table as well +
val customers : List<Component> // = ...
+val records: List<ComponentLifecycleRecord> = customers.map { it.toLifeCycleRecord() }
+
+records.asDataFrame()
+This transforms the customers straight into a krangl dataframe with the following structure
A DataFrame: 1034 x 11
+ component createdAt inCurrent inData inDataSince inInterrupted inPassive
+ 1 Vehicle.1 0.366 0 989.724 10.276 0 0
+ 2 Vehicle.2 1.294 0 984.423 15.577 0 0
+ 3 Vehicle.3 1.626 0 989.724 10.276 0 0
+ 4 Vehicle.4 2.794 0 989.724 10.276 0 0
+and 1024 more rows, and and 4 more variables: inScheduled, inStandby, inWaiting
+Clearly if needed, the user may also work with the records directly. For instance to configure a visualization.
+Running a simulation just once, often does not provide sufficient insights into the dynamics of the system under consideration. Often, the user may want to execute a model many times with altered initial conditions, and then perform a statistical analysis over the output. This is also considered as what-if analyis. See here for simple example.
+By design kalasim does not make use of parallelism. So when scaling up execution to run in paralell, we need to be careful, that the internal dependency injection (which relates by default to a global context variable) does not cause trouble. See here for an example that defines a parameter grid to be assessed with multi-threading with a simulation run per hyper-parameter.
To prevent memory leaks, the environment just keeps track of scheduled components, that is components that are queued for execution. In some situations the user may want to track all components irrespective of their queuing status. This can be achieved by setting up a component collector before creating the components
+createSimulation{
+ val cc = componentCollector()
+
+ // create components
+ Component("foo")
+ Component("bar")
+
+ // analyze all components created until this point
+ cc.size // will be 2
+}
+