From 2858e366bf91b059b8742e689ba6168f796f6ca6 Mon Sep 17 00:00:00 2001 From: Sergio Souza Costa Date: Thu, 30 Apr 2026 08:11:49 -0300 Subject: [PATCH] paper update --- paper.bib | 31 ++++++++++++++++++++++++++ paper.md | 66 +++++++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 83 insertions(+), 14 deletions(-) diff --git a/paper.bib b/paper.bib index 2ad16c7..d335054 100644 --- a/paper.bib +++ b/paper.bib @@ -126,3 +126,34 @@ @software{DisSModelSysDyn publisher = {GitHub}, url = {https://github.com/DisSModel/dissmodel-sysdyn} } + +@article{Pontius2008, + author = {Pontius, Robert Gilmore and Peethambaram, Sneha and Castella, Jean-Christophe}, + title = {Comparison of Three Maps at Multiple Resolutions: a Case Study of Land Change Simulation in Cho Don District, Vietnam}, + journal = {Annals of the Association of American Geographers}, + year = {2008}, + volume = {98}, + number = {1}, + pages = {28--49} +} + + +@article{Willmott2005, + author = {Willmott, Cort J. and Matsuura, Kenji}, + title = {Advantages of the mean absolute error ({MAE}) over the root mean + square error ({RMSE}) in assessing average model performance}, + journal = {Climate Research}, + year = {2005}, + volume = {30}, + pages = {79--82} +} + + +@article{Veldkamp1996, + author = {Veldkamp, A. and Fresco, L. O.}, + title = {{CLUE}: a conceptual model to study the conversion of land use and its effects}, + journal = {Ecological Modelling}, + year = {1996}, + volume = {85}, + pages = {253--270} +} \ No newline at end of file diff --git a/paper.md b/paper.md index c8c513f..611b16c 100644 --- a/paper.md +++ b/paper.md @@ -75,7 +75,8 @@ Beyond simulation execution, reproducibility is a first-class concern in DisSMod The `executor` module provides a standardised lifecycle — `validate → load → run → save` — that captures provenance metadata (input checksums, parameters, timing, output paths) in an `ExperimentRecord` object automatically generated for every run. This -design ensures that results produced locally or via CLI are fully traceable without additional instrumentation by the modeller. +design ensures that results produced locally or via CLI are fully traceable without +additional instrumentation by the modeller. ## State of the Field @@ -138,13 +139,19 @@ explicit `fmt` argument. For cloud deployments, the same API resolves interactive dashboards, and `RasterMap` for step-by-step raster rendering in both headless and interactive modes. -The extensibility of DisSModel's class hierarchy has already produced two domain -packages distributed independently on PyPI: `dissmodel-ca` [@DisSModelCA], which -provides ready-to-use Cellular Automata patterns built on `RasterCellularAutomaton`, -and `dissmodel-sysdyn` [@DisSModelSysDyn], which adds System Dynamics compartmental -models as first-class DisSModel components. Both packages follow the same -`ModelExecutor` contract and serve as reference implementations for researchers -building their own domain extensions. +The extensibility of DisSModel's class hierarchy has already produced domain +packages distributed independently on PyPI. `dissmodel-ca` [@DisSModelCA] provides +ready-to-use Cellular Automata patterns built on `RasterCellularAutomaton`. +`dissmodel-sysdyn` [@DisSModelSysDyn] adds System Dynamics compartmental models as +first-class DisSModel components. `DisSLUCC-Continuous` [@DisSLUCCContinuous] +implements the continuous LUCC modeling components of the LUCCME framework — Demand, +Potential, and Allocation — following the three-pillar architecture proposed by +@Veldkamp1996 and @Verburg2004, on both vector and raster substrates and following +the same `ModelExecutor` contract. This last package establishes an explicit Python +counterpart to the original TerraME/LUCCME stack, where DisSModel occupies the role +of TerraME and DisSLUCC-Continuous occupies the role of LUCCME. All three packages +serve as reference implementations for researchers building their own domain +extensions. ## Performance @@ -173,8 +180,9 @@ Bezerra et al. [@Bezerra2013], who discussed the integration of remote sensing a computational models to assess sea-level rise impacts on mangrove ecosystems. Building on this framework, the `coastal-dynamics` package [@CoastalDynamics] implements coupled flood and mangrove succession models over the same spatial domain on both -substrates. Running 20 simulation steps over a 60×60 synthetic grid (3,600 cells, -EPSG:31984) produces the following results: +substrates. Outputs are categorical land-use and soil classes; match percentage is +therefore the appropriate primary metric [@Pontius2008]. Running 20 simulation steps +over a 60×60 synthetic grid (3,600 cells, EPSG:31984) produces the following results: | Band | Match % | MAE | RMSE | Max Error | Cells | |------|--------:|----:|-----:|----------:|------:| @@ -190,6 +198,27 @@ generated by this run captured the full execution provenance automatically: load phase 2.898 s (49.4%), run phase 2.972 s (50.6%), input SHA-256 checksum, and artifact paths — with zero additional instrumentation by the modeller. +**Domain validation — DisSLUCC-Continuous LUCC model.** The `DisSLUCC-Continuous` +package implements the continuous CLUE-like allocation algorithm [@Veldkamp1996], +in which each cell holds a fractional land-use proportion rather than a discrete +class. For continuous outputs, fixed-threshold match statistics are not meaningful for +real-valued spatial data [@Pontius2008]; MAE is the appropriate primary metric, +as it provides a directly interpretable measure of average model error [@Willmott2005]. Running 6 simulation steps over the Lab1 study area (6,574 cells) +and comparing against a TerraME/LUCCME reference result produces the following: + +| Comparison | MAE | RMSE | Max Error | Cells | +|---|----:|-----:|----------:|------:| +| Vector vs TerraME | 0.003583 | 0.006188 | 0.027355 | 6,574 | +| Raster vs TerraME | 0.003583 | 0.006188 | 0.027355 | 6,574 | +| Vector vs Raster | 0.000000 | 0.000000 | 0.000000 | 6,574 | + +Both substrates reproduce the TerraME/LUCCME reference with a MAE of 0.0036 in +[0,1] scale — consistent with expected floating-point divergence between independent +Lua and Python implementations of the same continuous allocation algorithm. Vector +and raster substrates are numerically identical (MAE = 0.000), confirming that the +3.6× performance gain of the raster substrate (39.9 ms/step vs 143.2 ms/step) +introduces no algorithmic divergence. + ## Research Impact Statement DisSModel provides a critical bridge for the environmental modeling community. By @@ -199,11 +228,20 @@ framework has already been instrumental in academic research at the **LambdaGeo* group (UFMA), supporting studies on mangrove ecosystem dynamics and land-use change, building upon established spatial modeling practices [@Verburg2004; @SantosJunior2025]. +The emergence of independent domain packages — `dissmodel-ca`, `dissmodel-sysdyn`, +`DisSLUCC-Continuous`, and `coastal-dynamics` — without modifications to the core +framework demonstrates that the `ModelExecutor` contract is stable and sufficient for +real-world modeling requirements. This is further evidenced by the DisSModel +Platform, a distributed execution environment currently under development that +already orchestrates both `DisSLUCC-Continuous` and `coastal-dynamics` in a shared +test infrastructure, running each through the same job queue without any change to +their scientific code. The platform validates the central design principle of +DisSModel: that simulation science should not need to be rewritten to run in +production. + This architecture positions DisSModel as the simulation layer in the Brazilian Earth Observation stack — complementary to SITS [@Simoes2021] for present-state land -classification and the Brazil Data Cube [@Ferreira2020] for satellite data -access — and is designed to scale toward Pangeo-style ensemble runs via Dask -delayed operations over shared loaded datasets. +classification and the Brazil Data Cube [@Ferreira2020] for satellite data access. ## AI Usage Disclosure @@ -212,4 +250,4 @@ Jules) to assist with structuring documentation, synthesising prior work, and generating submission checklists. All outputs were reviewed and validated by the human authors. -## References +## References \ No newline at end of file