feat!: introduce a Kotlin DSL to configure simulations

[MarcoFratta]

Summary

This PR introduces a Kotlin DSL for configuring Alchemist simulations and a KSP-based annotation processor that generates helper functions to make existing classes DSL-friendly and easier to use.

Changes

• Kotlin DSL for configuration (alchemist-loading)

  • Adds a type-safe Kotlin DSL as an alternative to YAML for defining simulations.
  • Integrates into the existing loading pipeline via a new Kotlin-based model provider.

• KSP-based annotation processor (alchemist-dsl-processor)

  • Uses KSP to scan annotated Alchemist classes and generate DSL helper functions.
  • Reduces boilerplate when exposing existing classes to the DSL.
  • Makes pre-existing classes compatible with the DSL without changing their APIs.

Example

• YAML Version

incarnation: sapere

variables:
  rate: &rate
    type: GeometricVariable
    parameters: [2, 0.1, 10, 9]
  size: &size
    type: LinearVariable
    parameters: [5, 1, 10, 1]
  mSize: &mSize
    formula: -size
  sourceStart: &sourceStart
    formula: mSize / 10
  sourceSize: &sourceSize
    formula: size / 5

network-model:
  type: ConnectWithinDistance
  parameters: [0.5]

_send: &grad
  - time-distribution: *rate
    program: "{token, N, L} --> {token, N, L} *{token, N+#D, L add [#NODE;]}"
  - program: >
      {token, N, L}{token, def: N2>=N, L2} --> {token, N, L}
 
deployments:
  type: Grid
  parameters: [*mSize, *mSize, *size, *size, 0.25, 0.25, 0.1, 0.1]
  contents:
    - in:
        type: Rectangle
        parameters: [*sourceStart, *sourceStart, *sourceSize, *sourceSize]
      molecule: token, 0, []
  programs: *grad

• Kotlin DSL Version

simulation(incarnation) {
    val rate: Double by variable(GeometricVariable(2.0, 0.1, 10.0, 9))
    val size: Double by variable(LinearVariable(5.0, 1.0, 10.0, 1.0))

    val mSize by variable { -size }
    val sourceStart by variable { mSize / 10.0 }
    val sourceSize by variable { size / 5.0 }
    networkModel = ConnectWithinDistance(0.5)
    deployments {
        deploy(grid(mSize, mSize, size, size, 0.25, 0.25, 0.1, 0.1)) {
            inside(Rectangle(sourceStart, sourceStart, sourceSize, sourceSize)) {
                molecule = "token, 0, []"
            }
            programs {
                all {
                    timeDistribution(rate.toString())
                    program = "{token, N, L} --> {token, N, L} *{token, N+#D, L add [#NODE;]}"
                }
                all {
                    program = "{token, N, L}{token, def: N2>=N, L2} --> {token, N, L}"
                }
            }
        }
    }
}

[sonarqubecloud]

Please retry analysis of this Pull-Request directly on SonarQube Cloud

[sonarqubecloud]

Quality Gate passed

Issues
13 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud