holgerbrandl / kalasim

Discrete Event Simulator

kalasim

Discrete Event Simulator

kalasim is a discrete event simulator. It provides a statically typed API, dependency injection, modern persistence, structured logging and automation capabilities.

kalasim is designed for simulation practitioners, process analysts and industrial engineers, who need to go beyond the limitations of existing simulation tools to model and optimize their business-critical use-cases.

In contrast to many other simulation tools, kalasim is neither low-code nor no-code. It is code-first to enable change tracking, scaling, refactoring, CI/CD, unit-tests, and the rest of the gang that makes simulation development fun.

Documentation

All docs are hosted under http://www.kalasim.org/

kalasim's Issues

Make examples interactive with kotlin-playground

See https://github.com/etBrains/kotlin-playground and https://play.data2viz.io/documentation/scales/ for visualization examples and https://jetbrains.github.io/kotlin-playground/examples/

Add support for DurationUnit in distributions

To remove any doubt about what time unit is about to samples we could potentially add more support API using kotlin.time.DurationUnit

val waitingTimeDist = exponential<Seconds>(30)

or similar.

• Implementation (completed as part of v0.9)
• Documentation

Add TrafficLightController

To make intro-sim more useful we should explore how to add a TrafficLightController in the datalore example notebook https://datalore.jetbrains.com/notebook/WdAb9Z324er3ylG3e8nEbp/7w4nof8rUl4WLqyNblOovn/

Automate documentation build with github actions

See https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-github-actions

Add support for triangular distribution

Allow users to mimic: yield self.hold(sim.Triangular(8, 15, 12).sample())

ResourceEvents should detail out how long request was pending

Override random and shuffled in Component

This will help to reduce randomization errors

    public inline fun <T> Collection<T>.random(): T {
        return random(env.random)
    }

Find a more concise way to activate a new processes

Currently we need to yield(activate(process = Harvester::harvesting)) which seems too tedious. The average user will struggle is likely to struggle with this part of the API.

We could introduce a new verb such as activate(process) or simply change activate.
`

Add support api to create UUIDs with engine-controlled randomization

fyi @MohidQaiser

Add a standard logging library

I have been using https://github.com/MicroUtils/kotlin-logging for years and it works great.

The only thing required to enable it for a given class is to make its companion object inherit from KLogging:

companion object : KLogging()

You then get a local logger value and can add as much logging instrumentation as you want and not worry about overhead because the actions are all lambdas, which are not evaluated if the call level does not warrant it.

Have a look and see what you think.

Website throws certificate error when being used via https:// without www prefix

https://www.kalasim.org works just fine,
but https://kalasim.org/ throws a warning/error:

Same in other browsers.

https://www.sslshopper.com/ssl-checker.html#hostname=kalasim.org
and
https://www.sslshopper.com/ssl-checker.html#hostname=www.kalasim.org
report that different certificates are being used.

Domain.com support suggested that this is a problem with github.com

Remodel distributions API to better support Duration requirements in `hold()`

Currently, all distributions emit just numbers, in most demos and examples they are used to sample durations.

(x) Adapt API or add wrapper

Adopt new duration API introduced in kotlin v1.6

See https://blog.jetbrains.com/kotlin/2021/11/kotlin-1-6-0-is-released/

Also, the improved suspend support could be evaluated to further simplify process definitions.

Push now from Component up to SimulationEntity

Docs use incorrect request syntax

The example in https://www.kalasim.org/basics/ must release the clerks or - even better - should use a request scope.

Use a fibonacci heap to increase event list performance

Currently, we use a PriorityQueue with a remove-readd pattern on changes to schedule-time. Potentially this could be done more efficiently using a FibonacciHeap. See https://stackoverflow.com/questions/1871253/updating-java-priorityqueue-when-its-elements-change-priority

Refactor LevelStatRecord to use TickTime

Also, consider adding asDataFrame as support API directly on the timeline

Consider if resources claimers could be a list instead of a queue for better performance

Simulation components must not have same name

The engine should throw an exception. Maybe this could be made configuable

Fix traffic to use modern createSimulation API

See https://www.kalasim.org/examples/traffic/

Wait should allow to provide description

Depletable resources lack good API, documentation and test coverage

• Refer to shipyard in docs
• Refactor Gasstation to use more modern API and jupyter
• Highlight hydrate production as integration study
• Rework documentation of depletable resources
• Improve test coverage and include examples into test-suite

Allow merging of simulations

It shall support the following API

val env1 = Environment()
val env2 = Environment()

val envMerged = env1 + env2
envMerged.run(10)

This will allow modelling more complex child-parent relations separately. E.g. a department of a store could be modelled and then be bound into a shopping mall model itself.

Note: Unless we can support branching, the original environments will not be functional by themself after merging.

Prepare simulation visualization with jetpack compose

See https://medium.com/mobile-app-development-publication/jetpack-compose-animation-under-50-lines-using-k5-compose-playground-bef35060c471 for examples

Add component name auto-indexing

Similar to salabim, components should have auto-indexing if the name ends with a comma/dot

• Create test-coverage
• Implementation
• Review contract
• Update documentation

Provide a more declarative way to implement components

To create a custom component, currently, the user has to

val c = object : Component(){
    override fun process() = sequence { 
        hold(1)
    }
}

But it would be super-cool if she could just do something like

val c = object : Component(){
    hold(1)
}

However, it seems impossible to implement this feature because the underlying building would require multiple receivers (SeqeneceScope and this@Component) for functioning. This is not yet possible with kotlin, so this ticket is blocked by https://youtrack.jetbrains.com/issue/KT-10468.

Improve wait syntax

// current
wait(StateRequest(state) { it!=null })

// better
wait(state){ it!=null }

Provide visualization example via plotly.kt

See https://github.com/mipt-npm/plotly.kt/blob/master/examples/src/main/kotlin/dynamicServer.kt for a dynamic websocket example

Update koin to v3.1

See InsertKoinIO/koin#939 (comment)

Use moshi or jackson instead of gson

https://kotlin.christmas/2020/8

• https://www.ericthecoder.com/2020/10/13/benchmarking-gson-vs-jackson-vs-moshi-2020/
• https://stackoverflow.com/questions/239280/which-is-the-best-alternative-for-java-serialization

Provide better randomness abstraction

All supported commons-math distributions shall be wrapped to use env.rg by default.

Add optional wall time support to built in monitors

java.lang.IllegalStateException: KoinApplication has not been started

kalasim 0.6.6

fun main() {
    val devices = Resource(name = "devices", capacity = 1)
}

Exception in thread "main" java.lang.IllegalStateException: KoinApplication has not been started
	at org.koin.core.context.GlobalContext.get(GlobalContext.kt:35)
	at org.kalasim.Resource.<init>(Resource.kt:42)
	at MainKt.main(Main.kt:7)
	at MainKt.main(Main.kt)

How could I start KoinApplication?

Performance Tuning section is outdated

https://www.kalasim.org/advanced/#performance-tuning needs to be adjusted to API changes and additions.

Optimize MetricTime API

• get rid of Number, see https://kotlinlang.slack.com/archives/C0B8Q383C/p1641757248000700

Add some benchmark to prevent performance regressions

https://github.com/Kotlin/kotlinx-benchmark

`display()` should enforce time range in kravis

display ranges should be enforced internally when using kravis via xlim.

Currently blocked by holgerbrandl/kravis#30

collect() has unclear semantics

A common usecase is to filter for just some events of interest. This should be definable at the collector declaration site, but isn't in v0.7.92:

val log = sim.collect<ResourceActivityEvent>().filter{ it.bla}

It fails to respect request priority when competing with requests of claimable quantity

fyi @MohidQaiser

make trace logger width configurable

Currently its configuration is internal only

Optionally disallow use of untyped duration when tick-transform is defined

When a user has defined a tick-transform in a model it should optionally support disallowing untyped use of hold etc.

sim.tickTransform = TickTransform(TimeUnit.MINUTES)
sim.enforceTypedDurations = true
...
hold(3) // should fail because possible incorrect/unintenional use of wrong unit
hold(3.minutes) // should work

In a second iteration, kalasim may also want to enforce a tick-unit when creating a simulation (i.e. val sim = Environment(TimeUnit.MINUTES)). This would make hold(2) impossible: The user would always need to state her intent about the duration by providing a tick-unit.

FYI @MohidQaiser

Difference of ticktime should be duration and not Double

Implement tick metrics monitor

See https://www.kalasim.org/advanced/#operational-control for the specification of this feature.

Component creation order is wrong in clerk queue example

The correct event order when running Bank_1_clerk.kt should be

   30       0.000 main                 current                              
   32                                  customergenerator.0 create           
   32                                  customergenerator.0 activate         scheduled for      0.000 @    6  process=process
   33                                  clerk.0 create                       
   33                                  clerk.0 activate                     scheduled for      0.000 @   21  process=process
   34                                  waitingline create                   
   36                                  main run +50.000    

but instead, we obtain

.00                            main                     DATA        create
.00   main
.00                            CustomerGenerator.1      DATA        create
.00                            CustomerGenerator.1      DATA        activate
.00                            main                     CURRENT     run +50.0
.00   CustomerGenerator.1
.00                                                                 create ComponentQueue.1
.00                            Clerk.1                  DATA        create
.00                            Clerk.1                  DATA        activate

The component queue and the clerk should be created before main is rescheduled.

This problem is caused by InsertKoinIO/koin#801

Allow branching of simulations

To enable different trajectories (with controlled randomization), the user may want to branch simulations at a specific time.

Example

// current API 
val sim  : Environment = createSimulation{ 
// define simulation entities here
}

// run it for 100 ticks
sim.run(100)

// inspect some metric (see https://www.kalasim.org/analysis/)
sim.gatherStatistic()


// Pseudocode/Desired API from here on 
val branches : List<Environment> = sim.branch(100)

val branchStats = branches.forEach { it.run(100) }.map{ it.gatherStatistic() }

To do so we must persist the entire graph including koin, monitors, the environment (including its queue) and process states (which are modelled as kotlin.sequences.Sequence iterators). Naturally - by design of kalasim - user-specific code will also leak into the graph to be persisted.

• The feature would also provide means to have file-format for saving/loading simulations
• Such a feature would also prepare for distributed simulation, where simulations are packed and shipped over the network to other compute nodes

Current state
✔️ Framework evaluation -> kryo it is, see evaluation branch https://github.com/holgerbrandl/kalasim/tree/kryoeval
✔️ Persist koin
✔️ Persist main entities and environment
✔️ Deserialize environment including sequence iterators of process definitions (graph looks good and runs up to

kalasim/modules/persistence/src/main/kotlin/Kryo.kt

Line 77 in 9d383e0

val restored = kryo.readClassAndObject(input) as Environment

)
❌ Run deserialized environment--> Fails to run, which boils to sequence iterators being not serializable as of now in https://github.com/holgerbrandl/kryo-kotlin-sam/blob/master/src/main/kotlin/simpleproc/SimpleProc.kt (see Kotlin/kotlinx.coroutines#76 and EsotericSoftware/kryo#867)

ATM example is outdated

https://www.kalasim.org/examples/atm_queue/

• the code is redundant
• it should be built from notebook
• it's not running in parallel
• koin-context is set incorrectly in resource

State trigger do not trigger

All waits are honoured irrespective of the trigger setting.

MetricEvent has incomplete json serialization

In particular tickWallDurationMs is missing.

• Complete json model
• Build unit tests to ensure that json of built-in event types is correct

Consider using koin context isolation

Instead of the custom model we should use context isolation to provide DI per simulation

https://insert-koin.io/docs/reference/koin-core/context-isolation/

Publish call-center as blog article

The call-center is a great example to illustrate different modes of component and resource interaction.

It should be worked out in a blog article.

See https://github.com/holgerbrandl/kalasim/blob/master/docs/userguide/docs/articles/callcenter.ipynb

Note: This ticket is currently blocked by Kotlin/kotlin-jupyter#355. Without a fix, we can not execute the notebook.

• Detail out why a simple MMc queue does not do the job in a real business