feat!: introduce a Kotlin DSL to configure simulations

.gitignore

@@ -68,4 +68,3 @@ scala_compiler.xml
 # Exceptions
 # Keep 'build' packages in src directories
 !**/src/**/build/
-!**/src/**/build/**

alchemist-api/build.gradle.kts

@@ -16,7 +16,6 @@ dependencies {
     api(libs.jool)
     api(libs.listset)
     implementation(libs.kotlin.reflect)
-
     testImplementation(libs.kotlin.test)
 }
 

alchemist-api/src/main/kotlin/it/unibo/alchemist/boundary/dsl/AlchemistKotlinDSL.kt

@@ -0,0 +1,19 @@
+/*
+ * Copyright (C) 2010-2025, Danilo Pianini and contributors
+ * listed, for each module, in the respective subproject's build.gradle.kts file.
+ *
+ * This file is part of Alchemist, and is distributed under the terms of the
+ * GNU General Public License, with a linking exception,
+ * as described in the file LICENSE in the Alchemist distribution's top directory.
+ */
+
+package it.unibo.alchemist.boundary.dsl
+
+/**
+ * Annotation used to mark classes that should have DSL builder functions generated.
+ * When applied to a class, the DSL processor will generate a builder function
+ * that can be used in Alchemist DSL scripts to create instances of the annotated class.
+ */
+@Target(AnnotationTarget.CLASS)
+@Retention(AnnotationRetention.SOURCE)
+annotation class AlchemistKotlinDSL

alchemist-dsl-processor/build.gradle.kts

@@ -0,0 +1,16 @@
+import Libs.alchemist
+
+plugins {
+    id("kotlin-multiplatform-convention")
+}
+
+kotlin {
+    sourceSets {
+        val jvmMain by getting {
+            dependencies {
+                api(alchemist("api"))
+                implementation(libs.ksp.api)
+            }
+        }
+    }
+}

alchemist-dsl-processor/src/jvmMain/kotlin/it/unibo/alchemist/boundary/dsl/processor/DslBuilderProcessor.kt

@@ -0,0 +1,166 @@
+package it.unibo.alchemist.boundary.dsl.processor
+
+import com.google.devtools.ksp.getClassDeclarationByName
+import com.google.devtools.ksp.getConstructors
+import com.google.devtools.ksp.isPublic
+import com.google.devtools.ksp.processing.CodeGenerator
+import com.google.devtools.ksp.processing.Dependencies
+import com.google.devtools.ksp.processing.KSPLogger
+import com.google.devtools.ksp.processing.Resolver
+import com.google.devtools.ksp.processing.SymbolProcessor
+import com.google.devtools.ksp.symbol.KSAnnotated
+import com.google.devtools.ksp.symbol.KSClassDeclaration
+import com.google.devtools.ksp.symbol.KSType
+import com.google.devtools.ksp.validate
+import it.unibo.alchemist.boundary.dsl.AlchemistKotlinDSL
+import it.unibo.alchemist.boundary.dsl.processor.data.InjectableConstructor
+import it.unibo.alchemist.boundary.dsl.processor.extensions.asString
+import it.unibo.alchemist.boundary.dsl.processor.extensions.nameOrTypeName
+import it.unibo.alchemist.boundary.dsl.processor.extensions.typeName
+import it.unibo.alchemist.core.Simulation
+import it.unibo.alchemist.model.Environment
+import it.unibo.alchemist.model.Incarnation
+import it.unibo.alchemist.model.LinkingRule
+import it.unibo.alchemist.model.Node
+import it.unibo.alchemist.model.Reaction
+import it.unibo.alchemist.model.TimeDistribution
+import java.io.PrintWriter
+import java.nio.charset.StandardCharsets
+import org.apache.commons.math3.random.RandomGenerator
+
+/** Symbol processor that emits DSL helpers for `@AlchemistKotlinDSL` classes. */
+class DslBuilderProcessor(private val codeGenerator: CodeGenerator, private val logger: KSPLogger) : SymbolProcessor {
+
+    /**
+     * Processes every `@AlchemistKotlinDSL` symbol,
+     * generating helpers and returning unresolved ones.
+     */
+    override fun process(resolver: Resolver): List<KSAnnotated> {
+        context(resolver) {
+            logger.dslInfo("Starting processing")
+            val annotationName = AlchemistKotlinDSL::class.qualifiedName
+            check(!annotationName.isNullOrBlank()) {
+                "The Alchemist Kotlin DSL annotation name is invalid or missing: '$annotationName'"
+            }
+            logger.dslInfo("Alchemist DSL annotation: $annotationName")
+            return resolver.getSymbolsWithAnnotation(annotationName)
+                .fold(emptyList()) { invalidElements, symbol ->
+                    when {
+                        !symbol.validate() -> invalidElements + symbol
+                        else -> {
+                            if (symbol is KSClassDeclaration) {
+                                processClass(symbol)
+                            }
+                            invalidElements
+                        }
+                    }
+                }
+        }
+    }
+
+    context(resolver: Resolver)
+    private fun processClass(classDeclaration: KSClassDeclaration) {
+        logger.dslInfo("Processing class ${classDeclaration.simpleName.asString()}")
+        logger.dslInfo("Class qualified name: ${classDeclaration.qualifiedName?.asString()}")
+        val file = codeGenerator.createNewFile(
+            dependencies = classDeclaration.containingFile
+                ?.let { Dependencies(false, it) }
+                ?: Dependencies.ALL_FILES,
+            packageName = classDeclaration.packageName.asString(),
+            fileName = "${classDeclaration.simpleName.asString()}Factory.kt",
+        )
+        val writer = PrintWriter(file, true, StandardCharsets.UTF_8)
+        writer.println("// This file is generated by Alchemist DSL Processor. Do not edit manually.")
+        writer.println()
+        writer.println("package ${classDeclaration.packageName.asString()}")
+        writer.println()
+        val functionName = classDeclaration.simpleName.asString().replaceFirstChar { it.lowercaseChar() }
+        val injectableConstructors = classDeclaration.getConstructors()
+            .filter { it.isPublic() }
+            .mapNotNull { InjectableConstructor(it) }
+            .toList()
+        if (injectableConstructors.isEmpty()) {
+            logger.warn(
+                "No injectable constructors, ${AlchemistKotlinDSL::class.qualifiedName} will have no effect.",
+                classDeclaration,
+            )
+        }
+        injectableConstructors.forEach { (constructor, injectableParams, preservedParams) ->
+            val context = injectableParams.joinToString(prefix = "context(", postfix = ")") { param ->
+                "${param.nameOrTypeName()}: ${param.type.asString()}"
+            }
+            writer.println(context)
+            val typeParameters = constructor.typeParameters.takeIf { it.isNotEmpty() }
+                ?.joinToString(prefix = "<", postfix = "> ") { typeArgument ->
+                    buildString {
+                        if (typeArgument.isReified) {
+                            append("reified ")
+                        }
+                        append(typeArgument.name.asString())
+                    }
+                }
+                .orEmpty()
+            val parameters = preservedParams.joinToString(separator = NEWLINE_INDENT) { parameter ->
+                buildString {
+                    if (parameter.isCrossInline) {
+                        append("crossinline ")
+                    }
+                    if (parameter.isNoInline) {
+                        append("noinline ")
+                    }
+                    if (parameter.isVararg) {
+                        append("vararg ")
+                    }
+                    append(
+                        "${parameter.name?.asString()}: ${parameter.type.asString()}",
+                    )
+                }
+            }
+            val whereClause = constructor.typeParameters
+                .flatMap { typeParam ->
+                    typeParam.bounds.map { bound ->
+                        "${typeParam.simpleName.asString()} : ${bound.asString()}"
+                    }
+                }
+                .takeIf { it.isNotEmpty() }
+                ?.joinToString(separator = NEWLINE_INDENT, prefix = "where\n    ", postfix = "\n")
+                .orEmpty()
+            val arguments = constructor.parameters.joinToString(NEWLINE_INDENT) {
+                buildString {
+                    if (it.isVararg) {
+                        append("*")
+                    }
+                    append(it.nameOrTypeName())
+                }
+            }
+            writer.println(
+                """
+                    |fun $typeParameters$functionName(
+                    |    $parameters
+                    |) $whereClause= ${classDeclaration.typeName}(
+                    |    $arguments
+                    |)
+                """.trimMargin(),
+            )
+        }
+    }
+
+    internal companion object {
+
+        const val NEWLINE_INDENT = ",\n|    "
+
+        private fun KSPLogger.dslInfo(message: String) = info("${DslBuilderProcessor::class.simpleName}: $message")
+
+        context(resolver: Resolver)
+        fun injectableTypes(): Set<KSType> = sequenceOf(
+            resolver.getClassDeclarationByName<Environment<*, *>>(),
+            resolver.getClassDeclarationByName<Incarnation<*, *>>(),
+            resolver.getClassDeclarationByName<LinkingRule<*, *>>(),
+            resolver.getClassDeclarationByName<Node<*>>(),
+            resolver.getClassDeclarationByName<RandomGenerator>(),
+            resolver.getClassDeclarationByName<Reaction<*>>(),
+            resolver.getClassDeclarationByName<Simulation<*, *>>(),
+            resolver.getClassDeclarationByName<TimeDistribution<*>>(),
+        ).map { checkNotNull(it).asStarProjectedType() }.toSet()
+    }
+}

alchemist-dsl-processor/src/jvmMain/kotlin/it/unibo/alchemist/boundary/dsl/processor/DslBuilderProcessorProvider.kt

@@ -0,0 +1,13 @@
+package it.unibo.alchemist.boundary.dsl.processor
+
+import com.google.devtools.ksp.processing.SymbolProcessor
+import com.google.devtools.ksp.processing.SymbolProcessorEnvironment
+import com.google.devtools.ksp.processing.SymbolProcessorProvider
+
+/**
+ * Provider for [DslBuilderProcessor] that creates instances for KSP processing.
+ */
+class DslBuilderProcessorProvider : SymbolProcessorProvider {
+    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor =
+        DslBuilderProcessor(environment.codeGenerator, environment.logger)
+}

alchemist-dsl-processor/src/jvmMain/kotlin/it/unibo/alchemist/boundary/dsl/processor/data/InjectableConstructor.kt

@@ -0,0 +1,35 @@
+/*
+ * Copyright (C) 2010-2025, Danilo Pianini and contributors
+ * listed, for each module, in the respective subproject's build.gradle.kts file.
+ *
+ * This file is part of Alchemist, and is distributed under the terms of the
+ * GNU General Public License, with a linking exception,
+ * as described in the file LICENSE in the Alchemist distribution's top directory.
+ */
+
+package it.unibo.alchemist.boundary.dsl.processor.data
+
+import com.google.devtools.ksp.processing.Resolver
+import com.google.devtools.ksp.symbol.KSFunctionDeclaration
+import com.google.devtools.ksp.symbol.KSValueParameter
+import it.unibo.alchemist.boundary.dsl.processor.extensions.isInjectable
+
+internal data class InjectableConstructor(
+    val constructor: KSFunctionDeclaration,
+    val injectableParameters: List<KSValueParameter>,
+    val preservedParameters: List<KSValueParameter>,
+) {
+    companion object {
+        context(resolver: Resolver)
+        operator fun invoke(constructor: KSFunctionDeclaration): InjectableConstructor? {
+            val (injectable, preserved) = constructor.parameters.partition { it.type.resolve().isInjectable() }
+            return when {
+                injectable.isNotEmpty() && injectable.toSet().size == injectable.size && injectable.none {
+                    it.isVararg
+                } ->
+                    InjectableConstructor(constructor, injectable, preserved)
+                else -> null
+            }
+        }
+    }
+}

alchemist-dsl-processor/src/jvmMain/kotlin/it/unibo/alchemist/boundary/dsl/processor/extensions/KSDeclarationExtensions.kt

@@ -0,0 +1,15 @@
+/*
+ * Copyright (C) 2010-2025, Danilo Pianini and contributors
+ * listed, for each module, in the respective subproject's build.gradle.kts file.
+ *
+ * This file is part of Alchemist, and is distributed under the terms of the
+ * GNU General Public License, with a linking exception,
+ * as described in the file LICENSE in the Alchemist distribution's top directory.
+ */
+
+package it.unibo.alchemist.boundary.dsl.processor.extensions
+
+import com.google.devtools.ksp.symbol.KSDeclaration
+
+internal val KSDeclaration.typeName: String
+    get() = qualifiedName?.asString()?.takeIf { it.isNotEmpty() } ?: simpleName.asString()

alchemist-dsl-processor/src/jvmMain/kotlin/it/unibo/alchemist/boundary/dsl/processor/extensions/KSFunctionDeclarationExtensions.kt

@@ -0,0 +1,20 @@
+/*
+ * Copyright (C) 2010-2025, Danilo Pianini and contributors
+ * listed, for each module, in the respective subproject's build.gradle.kts file.
+ *
+ * This file is part of Alchemist, and is distributed under the terms of the
+ * GNU General Public License, with a linking exception,
+ * as described in the file LICENSE in the Alchemist distribution's top directory.
+ */
+import com.google.devtools.ksp.symbol.KSFunctionDeclaration
+import com.google.devtools.ksp.symbol.KSType
+import com.google.devtools.ksp.symbol.KSValueParameter
+
+/**
+ * Finds a public constructor for the given class declaration.
+ * Prefers the primary constructor, otherwise returns the constructor
+ * with the most parameters.
+ *
+ * @return The found constructor, or null if no suitable constructor exists
+ */
+internal val KSFunctionDeclaration.parameterTypes: List<KSType> get() = parameters.map { it.type.resolve() }

alchemist-dsl-processor/src/jvmMain/kotlin/it/unibo/alchemist/boundary/dsl/processor/extensions/KSTypeExtensions.kt

@@ -0,0 +1,17 @@
+/*
+ * Copyright (C) 2010-2025, Danilo Pianini and contributors
+ * listed, for each module, in the respective subproject's build.gradle.kts file.
+ *
+ * This file is part of Alchemist, and is distributed under the terms of the
+ * GNU General Public License, with a linking exception,
+ * as described in the file LICENSE in the Alchemist distribution's top directory.
+ */
+
+package it.unibo.alchemist.boundary.dsl.processor.extensions
+
+import com.google.devtools.ksp.processing.Resolver
+import com.google.devtools.ksp.symbol.KSType
+import it.unibo.alchemist.boundary.dsl.processor.DslBuilderProcessor
+
+context(resolver: Resolver)
+internal fun KSType.isInjectable() = DslBuilderProcessor.injectableTypes().any { it.isAssignableFrom(this) }

alchemist-dsl-processor/src/jvmMain/kotlin/it/unibo/alchemist/boundary/dsl/processor/extensions/KSTypeReferenceExtensions.kt

@@ -0,0 +1,28 @@
+/*
+ * Copyright (C) 2010-2025, Danilo Pianini and contributors
+ * listed, for each module, in the respective subproject's build.gradle.kts file.
+ *
+ * This file is part of Alchemist, and is distributed under the terms of the
+ * GNU General Public License, with a linking exception,
+ * as described in the file LICENSE in the Alchemist distribution's top directory.
+ */
+
+package it.unibo.alchemist.boundary.dsl.processor.extensions
+
+import com.google.devtools.ksp.symbol.KSTypeParameter
+import com.google.devtools.ksp.symbol.KSTypeReference
+
+internal fun KSTypeReference.asString(): String = buildString {
+    val type = resolve()
+    when (val declaration = type.declaration) {
+        is KSTypeParameter -> append(declaration.simpleName.asString())
+        else -> append(declaration.typeName)
+    }
+    if (type.arguments.isNotEmpty()) {
+        append(
+            type.arguments.joinToString(prefix = "<", postfix = ">") {
+                it.type?.asString() ?: "*"
+            },
+        )
+    }
+}

alchemist-dsl-processor/src/jvmMain/kotlin/it/unibo/alchemist/boundary/dsl/processor/extensions/KSValueParameterExtensions.kt

@@ -0,0 +1,15 @@
+/*
+ * Copyright (C) 2010-2025, Danilo Pianini and contributors
+ * listed, for each module, in the respective subproject's build.gradle.kts file.
+ *
+ * This file is part of Alchemist, and is distributed under the terms of the
+ * GNU General Public License, with a linking exception,
+ * as described in the file LICENSE in the Alchemist distribution's top directory.
+ */
+
+package it.unibo.alchemist.boundary.dsl.processor.extensions
+
+import com.google.devtools.ksp.symbol.KSValueParameter
+
+internal fun KSValueParameter.nameOrTypeName(): String = name?.asString()
+    ?: type.resolve().declaration.simpleName.asString().replaceFirstChar { it.lowercase() }

alchemist-dsl-processor/src/jvmMain/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider

@@ -0,0 +1 @@
+it.unibo.alchemist.boundary.dsl.processor.DslBuilderProcessorProvider

alchemist-full/build.gradle.kts

@@ -280,7 +280,7 @@ val packageTasks = validFormats.filterIsInstance<ValidPackaging>().map { packagi
 tasks.assemble.configure { dependsOn(packageTasks) }
 
 tasks.withType<AbstractArchiveTask> {
-    duplicatesStrategy = DuplicatesStrategy.WARN
+    duplicatesStrategy = DuplicatesStrategy.INCLUDE
 }
 
 publishing.publications {