Kotlin SD Toolkit or ksdtoolkit is a tool suitable for both:

• modelling larger, hierarchical system dynamics (SD) models (supporting modules) and
• for automatic generation of interactive simulators for multiple target platforms: desktop, web or mobile using Kotlin programming language.

Kotlin is a new (first appeared in 2011), statically-typed programming language, with:

• modern, more expressive syntax,
• null-pointer exception safety,
• both object-oriented and functional programming capabilities,
• interoperable with all existing Java libraries and frameworks, and
• since 2017 Google’s preferred language for Android application development;

Kotlin also excels in developing internal, domain-specific language (internal DSL), which allows adapting general-purpose language (e.g. Kotlin) to solve problems of specific domain (e.g. system dynamics).

ksdtookit consists of three modules:

1. ksdtoolkit-core - core module for SD modelling & simulation, with exporters (CSV, PNG), and desktop simulator app,
2. ksdtoolkit-mobapp - mobile simulator app module,
3. ksdtoolkit-webapp - web simulator app module.

Modelling Innovation / Product diffusion SD model (also known as Bass diffusion model).

// Static properties (optional)
companion object {
    const val TOTAL_POPULATION_VALUE = 10000            // [customer]
    const val ADVERTISING_EFFECTIVENESS_VALUE = 0.011   // [1/year]
    const val CONTACT_RATE_VALUE = 100                  // [1/year]
    const val ADOPTION_FRACTION_VALUE = 0.015           // []

    const val INITIAL_TIME_VALUE = 0    // [year]
    const val FINAL_TIME_VALUE = 10     // [year]
    const val TIME_STEP_VALUE = 0.25    // [year]
}

init {
    val model = Model()

    // Override default model properties
    model.initialTime = INITIAL_TIME_VALUE
    model.finalTime = FINAL_TIME_VALUE
    model.timeStep = TIME_STEP_VALUE
    model.integration = EulerIntegration()
    model.name = "Innovation/Product Diffusion Model" // optional

    val TOTAL_POPULATION = model.constant("TOTAL_POPULATION")
    val ADVERTISING_EFFECTIVENESS = model.constant("ADVERTISING_EFFECTIVENESS")
    val CONTACT_RATE = model.constant("CONTACT_RATE")
    val ADOPTION_FRACTION = model.constant("ADOPTION_FRACTION")

    val adoptionFromAdvertising =
        model.converter("adoptionFromAdvertising")
    val adoptionFromWordOfMouth =
        model.converter("adoptionFromWordOfMouth")

    val Potential_Adopters = model.stock("Potential_Adopters")
    val Adopters = model.stock("Adopters")

    val adoptionRate = model.flow("adoptionRate")

    Potential_Adopters.initialValue = { TOTAL_POPULATION }
    Adopters.initialValue = { 0.0 }

    TOTAL_POPULATION.equation = { TOTAL_POPULATION_VALUE }
    ADVERTISING_EFFECTIVENESS.equation = { ADVERTISING_EFFECTIVENESS_VALUE }
    CONTACT_RATE.equation = { CONTACT_RATE_VALUE }
    ADOPTION_FRACTION.equation = { ADOPTION_FRACTION_VALUE }

    adoptionFromAdvertising.equation = 
        { Potential_Adopters * ADVERTISING_EFFECTIVENESS }
    adoptionFromWordOfMouth.equation = 
        { CONTACT_RATE * ADOPTION_FRACTION *
        Potential_Adopters * Adopters / TOTAL_POPULATION }

    Potential_Adopters.equation = { - adoptionRate }
    Adopters.equation = { adoptionRate }

    adoptionRate.equation = 
        { adoptionFromAdvertising + adoptionFromWordOfMouth }

    val simulation = Simulation(model)

    simulation.outputs {
        CsvExporter("output.csv", ";"))     // Text
        PngExporter("chart.png"))           // Image
        WinSimulator()                      // Desktop
        WebSimulator()                      // Web
        MobSimulator()                      // Mobile
    }

    simulation.run()
}

• IntelliJ IDEA Ultimate - Integrated development environment
• OpenJDK 11 - Open Java development kit
• OpenJFX - Open JavaFX
• Gradle - Dependency management & build automation tool
• Vaadin 8 - Vaadin web framework
• Android SDK - Android software development kit

Whole ksdtoolkit project and all three project modules (ksdtoolkit-core, ksdtoolkit-mobapp, ksdtoolkit-webapp) are designed as Gradle project/modules (using Gradle Kotlin DSL). Therefore, use Gradlew Wrapper (gradlew in Windows or ./gradlew in Linux/Mac) to clean, build, test and run project/modules.

To run Gradle tasks, from IntelliJ one can use Terminal window (be in the root path where gradlew file is located). (Instead of Terminal window, an alternative is to install and use Gradle Plugin in IntelliJ.)

To clean and build whole project (and all modules) use:

gradlew clean build

(Close PngExporter and WinSimulator windows to allow build to finish).

To build only ksdtoolkit-core module use:

gradlew :ksdtoolkit-core:build

Build will also run all unit tests located in ./ksdtoolkit-core/src/test/kotlin/hr.unipu.ksdtookit/

The last unit test 5_SimulationOutputsTest contains output tests where e.g. WinSimulator is launched.

To build ksdtoolkit-webapp module and run web server use:

gradlew :ksdtoolkit-webapp:appStart

The web simulator will be accessible at: http://localhost:8080/

(Valid developer licence numbers are needed for using Vaadin Charts and Vaadin Spreadsheet).

In IntelliJ first create and launch Android emulator (Tools | Android | AVD Manager). To build ksdtoolkit-mobapp module and install apk file on Android emulator use:

gradlew :ksdtoolkit-mobapp:appStart

The mobile simulator will be automatically launched.

• Siniša Sovilj¹ sinisa.sovilj@unipu.hr
• Darko Etinger¹ darko.etinger@unipu.hr
• Krešimir Pripužić² kresimir.pripuzic@fer.hr

^{1 = Juraj Dobrila University of Pula, Faculty of Informatics, HR-52100 Pula, CROATIA
2 = University of Zagreb, Faculty of Electrical Engineering and Computing, HR-10000 Zagreb, CROATIA}

1. Sovilj, S., Etinger, D., Sirotić, Z. and Pripužić, K. (2021), System dynamics modeling and simulation with Kotlin. System Dynamics Review, 37: 227-240. https://doi.org/10.1002/sdr.1686

This project is licensed under the Apache License 2.0 license. See the LICENSE file for details.

Kotlin SD Toolkit was inspired by the great work of:

• Drost & Stein - System Dynamics Java-Framework,
• Schroeck - Business Prototyping Toolkit for Python.