Appendix E — Kotlin and KSL Setup

Learning objectives

After reading this appendix you should be able to:

install the tools needed to run the simulation examples
open the course code project and run an example
add your own model to the project

E.1 What You Need

Two things, and nothing else:

A JDK, version 21 or later. Temurin is a good default. Verify the installation with java -version at a terminal.
IntelliJ IDEA, Community Edition. It has Kotlin support built in and understands Gradle projects without configuration.

You do not need to install Kotlin, Gradle, or the KSL separately. The course code project carries a Gradle wrapper that downloads the correct versions of Gradle and Kotlin on first use, and Gradle downloads the KSL from Maven Central.

E.2 Getting the Course Code Project

The Kotlin examples live in their own repository, separate from the book:

https://github.com/rossetti/RossettiInventoryBookCode

Clone it if you have Git. An updated example then costs you one command rather than a second download:

git clone https://github.com/rossetti/RossettiInventoryBookCode.git
cd RossettiInventoryBookCode

If you do not have Git, use the Code button on that page and choose Download ZIP, then unpack it. Either way you end up with one directory, and that directory is the Gradle project. Open it in IntelliJ with File, then Open, and select the directory itself rather than a file inside it. IntelliJ recognizes the Gradle build and configures the rest on its own.

When a chapter says that its code is in code/, it means this project. The book uses the short name because the directory you unpack it under is yours to name.

E.3 What Is in It

The project’s structure mirrors the book:

build.gradle.kts       build configuration; the KSL dependency lives here
settings.gradle.kts
gradlew, gradle/       the Gradle wrapper
src/main/kotlin/inventory/
  <topic>/             one package per subject
src/test/kotlin/       the checks that pin what the book prints
data/                  the demand histories used for fitting

A package is named for its subject, so inventory.dynamiclotsizing holds the code of Chapter 5 and inventory.newsvendor holds the code of Chapter 7. Chapter numbers move when a book is revised and subjects do not, which is the same reason the section labels you see in cross-references are semantic rather than numbered.

Notice the test directory. Every number this book prints from a program is asserted there, so ./gradlew test is a check that the copy you have agrees with the copy the book was written against. Run it once after you clone. If it passes, any later failure is yours and not the book’s, which is worth knowing before you start changing things.

E.4 Running Your First Model

From a terminal, in the project directory:

./gradlew run

The first run takes a minute while Gradle, Kotlin, and the KSL are downloaded; later runs start immediately. The default example evaluates a newsvendor order quantity by Monte Carlo simulation, using the final buy of the mower deck belt from Chapter 7 with its fitted normal demand, and prints expected profit across a grid of order quantities:

Expected profit by order quantity (10,000 replications each)
         Q     avg profit   half-width
       400       16905.21        52.62
       420       17402.01        61.77
       440       17708.05        72.49
       460       17861.59        85.22
       480       17817.87        96.08
       500       17792.08       105.77
       520       17514.23       115.26
       540       17088.56       124.98
       560       16740.80       132.01

Best quantity on this grid: Q = 460, expected profit 17861.59
Compare against the critical ratio solution -- see @sec-newsvendor.

Notice two things about that output before you go further. The critical ratio puts the optimal buy at 475 belts, and the grid’s flat top from 440 to 500 brackets it; the best point on the grid, 460, differs from its neighbors by less than their half-widths, so the simulation cannot tell 460 from 480 at ten thousand replications and does not pretend to. That agreement with the closed form is how you gain confidence that a simulation is built correctly. And the half-widths grow with the order quantity, because profit becomes more variable as more units are exposed to demand risk. A single replication would have told you neither.

To run it from IntelliJ instead, open the project directory as described in Section E.2 and use the gutter icon beside fun main.

E.5 Adding Your Own Model

Put the file in the package of the subject it belongs to, so a model of a continuous review policy goes in src/main/kotlin/inventory/continuousreview/ beside the chapter’s own examples. Give it a top-level fun main(). Kotlin compiles the top-level functions of a file named MyPolicy.kt into a class named MyPolicyKt, and that class name is what Gradle runs. To run your file from the terminal, pass the class as the mainClass property:

./gradlew run -PmainClass=inventory.continuousreview.MyPolicyKt

To make it the default instead, point application { mainClass } in build.gradle.kts at it; the block already reads the property and falls back to the newsvendor example when none is given. From IntelliJ, the gutter icon beside fun main runs the file with no configuration at all.

Keep the model’s inputs at the top of main as named values, as every example in the project does, so that the next reader can see what was assumed without reading the code that uses it. Thus, a model of your own is one file, one main, and one property on the command line.

E.6 The KSL Itself

The KSL is a large library, and this book uses a small part of it. For the library on its own terms, its packages, its process view, and its output analysis machinery, see Simulation Modeling using the KSL.

The version this course pins is declared in the project’s build.gradle.kts:

implementation("io.github.rossetti:KSLCore:R1.7.1")