Kotlin System Dynamics Toolkit

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.

Intro

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.

Usage

Example:

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

0. Setup

// 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]
}

1. Model

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

2. Entities

Constants

    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")

Converters

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

Stocks

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

Flows

    val adoptionRate = model.flow("adoptionRate")

Modules

3. Initial values

Stocks

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

4. Equations

Constants

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

Converters

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

Stocks

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

Flows

    adoptionRate.equation = 
        { adoptionFromAdvertising + adoptionFromWordOfMouth }

Modules

5. Simulation

    val simulation = Simulation(model)

6. Outputs

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

7. Run

    simulation.run()
}

Built With

• 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

Testing

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).

Desktop simulator

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.

Web simulator

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).

Mobile simulator

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.

Authors

• Siniša Sovilj1 [email protected]
• Darko Etinger1 [email protected]
• Krešimir Pripužić2 [email protected]

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

References

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

License

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

Acknowledgments

Kotlin SD Toolkit was inspired by the great work of:

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