feat(geospatial): add alchemist-geospatial module for real-world climate data

alchemist-full/build.gradle.kts

@@ -8,6 +8,7 @@
  */
 import Libs.alchemist
 import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
+import com.github.jengelman.gradle.plugins.shadow.transformers.AppendingTransformer
 import com.google.common.hash.Hashing
 import it.unibo.alchemist.build.commandExists
 import it.unibo.alchemist.build.isMac
@@ -81,6 +82,8 @@ tasks.withType<ShadowJar>().configureEach {
     isZip64 = true
     mergeServiceFiles()
     duplicatesStrategy = DuplicatesStrategy.INCLUDE
+    // EMF's plugin.properties must be merged if there are multiple entries
+    transform<AppendingTransformer> { resource = "plugin.properties" }
     destinationDirectory.set(rootProject.layout.buildDirectory.map { it.dir("shadow") })
 }
 

alchemist-geospatial/build.gradle.kts

@@ -0,0 +1,40 @@
+/*
+ * Copyright (C) 2010-2026, 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 Libs.alchemist
+
+plugins {
+    id("kotlin-jvm-convention")
+}
+
+dependencies {
+    api(alchemist("api"))
+
+    implementation(libs.cdm.core)
+    implementation(libs.cdm.grib)
+    implementation(libs.gson)
+    implementation(libs.guava)
+    implementation(libs.slf4j)
+
+    testImplementation(alchemist("maps"))
+    testImplementation(alchemist("test"))
+}
+
+publishing.publications {
+    withType<MavenPublication> {
+        pom {
+            contributors {
+                contributor {
+                    name.set("Emir Wanes Aouioua")
+                    email.set("emirwanes.aouioua@studio.unibo.it")
+                }
+            }
+        }
+    }
+}

alchemist-geospatial/gradle.properties

@@ -0,0 +1,10 @@
+#
+# Copyright (C) 2010-2026, Danilo Pianini and contributors listed in the main project's alchemist/build.gradle 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.
+#
+artifactId = alchemist-geospatial
+projectLongName = Alchemist Geospatial
+projectDescription = Integration of Copernicus/ECMWF Temporal Raster Data into the Alchemist Simulator

alchemist-geospatial/src/main/kotlin/it/unibo/alchemist/boundary/acquisition/CacheKey.kt

@@ -0,0 +1,23 @@
+/*
+ * Copyright (C) 2010-2026, 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.acquisition
+
+/**
+ * Deterministic identity of a request.
+ */
+fun interface CacheKey {
+
+    /**
+     * @return a **deterministic, file-system-safe** directory name derived *only* from what
+     * determines the downloaded bytes, so that equal content always maps to the same name. The
+     * returned name must be a single path segment: no separators (`/`, `\`), and safe on different OS.
+     */
+    fun toFileName(): String
+}

alchemist-geospatial/src/main/kotlin/it/unibo/alchemist/boundary/acquisition/CacheManager.kt

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2010-2026, 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.acquisition
+
+import java.nio.file.Path
+
+/**
+ * Manages disk-based cache directories identified by deterministic [CacheKey] requests.
+ *
+ * When a directory is requested via [getOrProduce], the manager resolves its path.
+ * If the directory is missing or empty, it automatically fetches and populates the
+ * data using the configured [provider].
+ *
+ * @param R the type of [CacheKey] accepted by this manager.
+ *
+ * @see ExternalDataProvider
+ * @see CacheKey
+ */
+interface CacheManager<in R : CacheKey> {
+
+    /**
+     * The provider responsible for populating the directory associated with the cache entry in
+     * [CacheManager.getOrProduce], in the event that it does not exist or is empty.
+     */
+    val provider: ExternalDataProvider<R>
+
+    /**
+     * Calculates and returns the directory where the data was cached via the [request].
+     *
+     * @param request the request used to calculate the deterministic directory path.
+     * @return the path to the directory containing the data.
+     */
+    fun getOrProduce(request: R): Path
+}

alchemist-geospatial/src/main/kotlin/it/unibo/alchemist/boundary/acquisition/CopernicusCacheManager.kt

@@ -0,0 +1,109 @@
+/*
+ * Copyright (C) 2010-2026, 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.acquisition
+
+import java.nio.file.FileSystemException
+import java.nio.file.Files
+import java.nio.file.Path
+import java.nio.file.StandardCopyOption
+import org.slf4j.LoggerFactory
+
+/**
+ * Filesystem cache of the directories produced by data providers. This is the **single** place
+ * where cache atomicity lives, once for every provider. It knows nothing about HTTP or the
+ * individual APIs, depending only on [CacheKey].
+ *
+ * This class considers **atomicity but non locking**: if two simultaneous cache-miss runs
+ * for the production of data, one wins the atomic rename, the other discards its own work.
+ * Wasteful in that rare case, but it never corrupts the cache.
+ *
+ * **Note!** The entries are **trust-based**: a present directory is assumed complete and valid: the content
+ * of a cache-hit is not re-verified. Manual alteration of a cache entry is out of contract.
+ *
+ * @param root cache root directory (e.g. `~/.alchemist/cache/geospatial`). Created on demand.
+ */
+class CopernicusCacheManager(override val provider: ExternalDataProvider<CopernicusRequest>, private val root: Path) :
+    CacheManager<CopernicusRequest> {
+
+    /**
+     * Temporary subdirectory, on the same filesystem as [root].
+     * (required for `ATOMIC_MOVE`).
+     */
+    private val tmpRoot: Path = root.resolve(TEMP_SUBDIR)
+
+    /**
+     * Returns the directory associated with [request], producing it if absent.
+     *
+     * On **cache hit** the existing directory is returned immediately.
+     * On **cache miss**, the [provider] runs into a temporary directory, its non-emptiness is
+     * validated, and it is then promoted to the final location with an atomic rename.
+     * If a concurrent process produced the same entry in the meantime, that one is used
+     * and the local work is discarded. If, for any reason, [provider] fails, the temporary
+     * directory is removed (no "poisoned" entry is left in cache).
+     *
+     * @param request request identity (to determine the directory name).
+     * @return the [Path] of the final cache directory, filled with data.
+     * @throws IllegalStateException if [provider] writes no file in the temporary directory.
+     */
+    override fun getOrProduce(request: CopernicusRequest): Path {
+        val finalDir = root.resolve(request.toFileName())
+        // cache hit: the directory already exists
+        if (Files.isDirectory(finalDir)) {
+            logger.info("Cache hit for '${request.toFileName()}': using $finalDir")
+            return finalDir
+        }
+        logger.info("Cache miss for '${request.toFileName()}': fetching data")
+        // cache miss (also creates root if it does not exist)
+        Files.createDirectories(tmpRoot)
+        val temp = Files.createTempDirectory(tmpRoot, request.toFileName())
+        var moved = false // becomes true if the directory gets promoted
+        try {
+            // tries to fill the directory with data
+            provider.fetch(request, temp)
+            check(hasData(temp)) { "Provider produced no files for '${request.toFileName()}'" }
+            moved = promote(temp, finalDir)
+            logger.info("Asset(s) cached in $finalDir")
+            return finalDir
+        } finally {
+            // deletes the temp directory if any accident occurs
+            if (!moved) temp.toFile().deleteRecursively()
+        }
+    }
+
+    /**
+     * Atomically promotes [temp] to [finalDir].
+     *
+     * @param temp the path of the temporary directory.
+     * @param finalDir the path of the final directory after [temp] gets promoted.
+     * @return true if this call performed the move, false if a concurrent peer had already
+     * produced [finalDir].
+     */
+    private fun promote(temp: Path, finalDir: Path): Boolean = try {
+        Files.move(temp, finalDir, StandardCopyOption.ATOMIC_MOVE)
+        true
+    } catch (raceLost: FileSystemException) {
+        if (!Files.isDirectory(finalDir)) throw raceLost
+        // peer won but temp dir still exists
+        false
+    }
+
+    /**
+     * Checks if [dir] directory holds at least one regular file.
+     *
+     * @return true if [dir] holds any regular file, false otherwise.
+     */
+    private fun hasData(dir: Path): Boolean =
+        Files.list(dir).use { entries -> entries.anyMatch { Files.isRegularFile(it) } }
+
+    private companion object {
+        private val logger = LoggerFactory.getLogger(CopernicusCacheManager::class.java)
+        private const val TEMP_SUBDIR = ".tmp"
+    }
+}