From 7ce35969ef1e7441b6ac92e7e1e2459a17245eb0 Mon Sep 17 00:00:00 2001 From: Sergio Souza Costa Date: Wed, 7 Oct 2026 14:35:33 -0300 Subject: [PATCH 1/7] docs(paper): align validation text with disslucc-benchmark - Use benchmark scenario IDs (lab01_md1643, lab15_md10) for the Lab1 and Lab15 results - Point validation to the public disslucc-benchmark instead of test file paths - State the MAE metric (final year; mean over all years 0.0026) and iteration counts - Replace per-step timings with whole-run timings from `make timing` - Describe the correctCellChange guard neutrally (field name mismatch) - Fellowship paragraph in the present tense (four fellows since September 2026) - Add DisSLUCCBenchmark to paper.bib --- paper.bib | 19 +++++++++++++++ paper.md | 71 +++++++++++++++++++++++++++++-------------------------- 2 files changed, 57 insertions(+), 33 deletions(-) diff --git a/paper.bib b/paper.bib index 0513a37..1c1163f 100644 --- a/paper.bib +++ b/paper.bib @@ -136,6 +136,25 @@ @software{DisSLUCC url = {https://github.com/DisSModel/disslucc} } +@software{DisSCube, + author = {Costa, Sérgio Souza}, + title = {{DisSCube}: Declarative spatial data cubes}, + version = {0.5.0}, + year = {2026}, + publisher = {Zenodo}, + doi = {10.5281/zenodo.23172450}, + url = {https://github.com/DisSModel/disscube} +} + +% TODO: tag the benchmark (v0.2.0) before the paper is final and update version/year below. +@software{DisSLUCCBenchmark, + author = {Costa, Sérgio Souza}, + title = {{disslucc-benchmark}: Reproducible validation of {disslucc} against the {LuccME} 3.1 labs}, + year = {2026}, + publisher = {GitHub}, + url = {https://github.com/LambdaGeo/disslucc-benchmark} +} + @software{TerraMEDocker, author = {Costa, Sérgio Souza}, title = {{terrame-docker}: {TerraME} 2.0.1 and {LuccME} in a container, with diff --git a/paper.md b/paper.md index d4542ce..9f5edf4 100644 --- a/paper.md +++ b/paper.md @@ -150,11 +150,11 @@ submitting author — the same researchers responsible for the DisSModel reimple validates the raster implementation against TerraME over the Maranhão Island dataset (50,496 cells, 19 steps): land use and soil match exactly at every checkpoint (MAE 0, max error 0), and elevation on 97.3% of cells within 1 mm -(MAE 0.00068 m) — match percentage being the appropriate metric for categorical +(MAE 0.00068 m; maximum absolute error 0.24 m against elevations of 1–58 m) — match percentage being the appropriate metric for categorical outputs [@PontiusEtAl2011]. In this scenario the flood component triggers no land-use transition and the golden files confirm TerraME does the same, so the -agreement above exercises mangrove migration; flooding is covered separately under -the laboratory parameters. Reproducible via the package's validation executor +agreement above exercises mangrove migration; flooding is only checked separately: a test confirms that it occurs under the +laboratory parameters (2,470 cells by step 11), but a step-by-step comparison with TerraME for that case is still pending. Reproducible via the package's validation executor against its committed golden files. Cross-substrate equivalence (60×60 synthetic grid, 3,600 cells, 10 steps) shows @@ -163,29 +163,29 @@ error 0.024 m), with raster at 2.1 ms/step against 84.2 ms/step for vector (40.1 speedup; the vector port follows TerraME's per-cell loops); the residual elevation divergence is floating-point rounding, not algorithmic disagreement. -**disslucc** [@DisSLUCC] implements the continuous CLUE-like allocation algorithm -[@Veldkamp1996]; MAE is the appropriate metric for its fractional outputs -[@PontiusEtAl2011; @Willmott2005]. Over the Lab1 study area (6,574 cells, 6 steps), -the raster implementation reproduces the TerraME/LUCCME reference at MAE = 0.0036 -(RMSE 0.0062, max error 0.027) in [0,1] scale, at 44.0 ms/step. The residual is a -single, deliberate deviation: LuccME's per-cell consistency correction -(`correctCellChange`) never executes, because its guard tests a misspelled -attribute, while `disslucc` runs it by default. With that step disabled -(`cell_correction=False`), `disslucc` matches TerraME in every simulated year, -including the number of convergence iterations per year (MAE < 1e-7). Reproducible via -`disslucc/tests/test_validation_lab1.py` and `test_goldens_per_year.py`, against -year-by-year reference outputs generated in a containerised TerraME -[@TerraMEDocker]; `disslucc/tests/test_benchmark_discriminance_lab1.py` confirms -that perturbing the regression coefficients breaks the tolerance criterion. - -The discrete CLUE-S-like allocation in `disslucc`, with a logistic-regression -potential, reproduces the Lab15 case study (Mojui, Pará 5,914 cells, 6 steps) -from the reference LuccME implementation [@LuccME] cell for cell — zero quantity and -zero allocation disagreement [@PontiusMillones2011] — at 10.3 ms/step. A shipped -discriminance test shows the final map is also reproduced by a trivial static ranking, -so the map alone validates only coefficient transcription; the convergence loop is -validated separately, as the number of CLUE-S iterations matches TerraME in every -simulated year (0, 67, 56, 56, 61, 61). +**disslucc as a second case.** `disslucc` [@DisSLUCC], a package built on DisSModel, +reimplements the LuccME demand, potential and allocation components (continuous CLUE-like +[@Veldkamp1996] and discrete CLUE-S-like). It is used here to test the `ModelExecutor` contract +and the raster substrate against a second TerraME application, not as a result of its own. Its +checks live in a separate, versioned benchmark [@DisSLUCCBenchmark] that compares every simulated +year, iteration counts included, with per-year outputs generated in a containerised TerraME +[@TerraMEDocker] and checked by SHA-256. Scenarios follow the LuccME test labs (`labNN`); the +`labNN_mdX` variants exercise the convergence loop. MAE suits fractional outputs +[@PontiusEtAl2011; @Willmott2005]. + +`lab01_md1643` (continuous, 6,574 cells, 6 steps) matches the reference with MAE = 0.0036 in the +final year (mean over years 0.0026, [0,1] scale). The residual is one deliberate deviation: +LuccME's per-cell correction (`correctCellChange`) never executes, because its guard reads a +field name that does not match the one defined, while `disslucc` runs it by default. Without it +(`cell_correction=False`) the match holds in every year, with identical iteration counts +(0, 0, 8, 26, 18, 17, 17; MAE < 1e-7). `lab15_md10` (discrete, 5,914 cells) reproduces the +reference cell for cell, with zero quantity and allocation disagreement [@PontiusMillones2011] +and identical iteration counts (0, 67, 56, 56, 61, 61); the final map alone only checks +coefficient transcription, and the iterations check the convergence loop. Overall, ten of the 21 +LuccME test labs and the two variants match with identical iteration counts and differences up to +3e-6 (single-precision paths). A validated lab runs in 0.1 to 0.5 s on the hardware above (median +of five; `make timing`), against 2 to 9 s for one uncontrolled TerraME run: informative, not a +speed ratio. ## Research Impact Statement @@ -205,12 +205,11 @@ INPE), whose doctoral work established BR-MANGUE's scientific foundation program (UFMA projects PVCBS4959-2025 and PVCBS4960-2025), a collaboration predating DisSModel itself [@Bezerra2025BM]. -Starting August 2026, the project receives its first undergraduate research -fellows, funded by UFMA and by CNPq. The 2026 development effort was oriented toward this milestone: -stabilizing the `ModelExecutor` contract so each fellow can own an independent -repository — `disslucc`, `brmangue-dissmodel`, or -`disscube` (a data-cube layer, a Python alternative to TerraME's -`fillCellularSpace`) — without core changes. +Since September 2026, four undergraduate research fellows, funded by UFMA and by CNPq, +are being trained on the project. The 2026 development effort prepared for this by stabilizing +the `ModelExecutor` contract, so that each fellow can own an independent repository — +`disslucc`, `brmangue-dissmodel`, or `disscube` [@DisSCube] (a data-cube layer, a Python alternative to +TerraME's `fillCellularSpace`) — without core changes. Studies such as @Bezerra2022, developed using LuccME, are the class of models `disslucc` aims to reproduce. A roadmap toward @@ -244,7 +243,13 @@ not involve generative AI. Development resumed in February–March 2026 with Cla (chat) used mainly for documentation; from April 2026, Gemini CLI accelerated code generation and refactoring; from June 2026, Claude Code (CLI) was used on newer satellite repositories such as `disslucc`, including the audit of the -validation routines against the original TerraME scripts. AI tools also assisted +validation routines against the original TerraME scripts. In September–October 2026, +in response to the review, Claude (Claude Code and chat) was also used to build the +separate `disslucc-benchmark` repository (scenario definitions, the comparison and +timing scripts, and a differential test against the original Lua code), to reorganize +`disslucc`, and to revise the validation text of this paper so that it matches the +benchmark; the reference results themselves come from the original TerraME/LuccME +code, run unmodified in a container. AI tools also assisted with writing in English, not the submitting author's native language. The scientific design — the TerraME compatibility contract, executor pattern, dual-substrate architecture, and validation methodology — predates and is From 668eb8e9e54eacc9c9d0ec071d093285591c05e3 Mon Sep 17 00:00:00 2001 From: Sergio Souza Costa Date: Wed, 7 Oct 2026 16:06:50 -0300 Subject: [PATCH 2/7] cite disslucc 0.5.0, brmangue-dissmodel 0.3.0 and disslucc-benchmark with Zenodo DOIs --- paper.bib | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/paper.bib b/paper.bib index 1c1163f..27b5c1c 100644 --- a/paper.bib +++ b/paper.bib @@ -106,8 +106,10 @@ @article{Ferreira2020 @software{BRMangue, author = {Costa, Sérgio Souza and Bezerra, Denilson da Silva and Sousa, Felipe Martins}, title = {{brmangue-dissmodel}: The BR-MANGUE coupled flood and mangrove succession model for DisSModel}, + version = {0.3.0}, year = {2026}, - publisher = {GitHub}, + publisher = {Zenodo}, + doi = {10.5281/zenodo.23220431}, url = {https://github.com/DisSModel/brmangue-dissmodel} } @@ -130,9 +132,10 @@ @software{DisSModelSysDyn @software{DisSLUCC, author = {Costa, Sérgio Souza}, title = {{disslucc}: Raster-only continuous and discrete LUCC allocation models for DisSModel}, - version = {0.4.0}, + version = {0.5.0}, year = {2026}, - publisher = {GitHub}, + publisher = {Zenodo}, + doi = {10.5281/zenodo.23219338}, url = {https://github.com/DisSModel/disslucc} } @@ -146,12 +149,13 @@ @software{DisSCube url = {https://github.com/DisSModel/disscube} } -% TODO: tag the benchmark (v0.2.0) before the paper is final and update version/year below. +% TODO: if a v0.2.0 release is made before the paper is final, add its version and DOI here. @software{DisSLUCCBenchmark, author = {Costa, Sérgio Souza}, title = {{disslucc-benchmark}: Reproducible validation of {disslucc} against the {LuccME} 3.1 labs}, year = {2026}, - publisher = {GitHub}, + publisher = {Zenodo}, + doi = {10.5281/zenodo.23169808}, url = {https://github.com/LambdaGeo/disslucc-benchmark} } From 26561e4e091b1f468d23a9af7f898003e8fc4bd7 Mon Sep 17 00:00:00 2001 From: Sergio Souza Costa Date: Wed, 7 Oct 2026 16:08:54 -0300 Subject: [PATCH 3/7] docs(paper): BR-MANGUE validation with both TerraME scenarios; cite released versions with DOIs --- paper.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/paper.md b/paper.md index 9f5edf4..4d23245 100644 --- a/paper.md +++ b/paper.md @@ -148,20 +148,21 @@ whose co-authors include Denilson da Silva Bezerra, Felipe Martins Sousa and the submitting author — the same researchers responsible for the DisSModel reimplementation. The `brmangue-dissmodel` package [@BRMangue] validates the raster implementation against TerraME over the Maranhão Island -dataset (50,496 cells, 19 steps): land use and soil match exactly at every -checkpoint (MAE 0, max error 0), and elevation on 97.3% of cells within 1 mm -(MAE 0.00068 m; maximum absolute error 0.24 m against elevations of 1–58 m) — match percentage being the appropriate metric for categorical -outputs [@PontiusEtAl2011]. In this scenario the flood component triggers no -land-use transition and the golden files confirm TerraME does the same, so the -agreement above exercises mangrove migration; flooding is only checked separately: a test confirms that it occurs under the -laboratory parameters (2,470 cells by step 11), but a step-by-step comparison with TerraME for that case is still pending. Reproducible via the package's validation executor -against its committed golden files. +dataset (50,496 cells). In the baseline scenario (19 steps) land use and soil match +exactly at every checkpoint, and elevation matches on 97.4% of cells within 1 mm +(MAE 0.00038 m; maximum absolute error 0.10 m against elevations of 1–58 m); match +percentage is the appropriate metric for categorical outputs [@PontiusEtAl2011]. In the +flooding scenario (the laboratory parameters, 2,469 cells flooded by step 11) soil +matches exactly and land use differs in fewer than 0.05% of cells, with elevation within +1 mm on 94.9% of cells after 10 steps. The residual elevation differences are +floating-point rounding in the order of summation, not a difference in the rules. Both +scenarios are reproducible via the package's validation executor. Cross-substrate equivalence (60×60 synthetic grid, 3,600 cells, 10 steps) shows -100% match for land use, soil, and elevation under tolerance (MAE 0.000959 m, max -error 0.024 m), with raster at 2.1 ms/step against 84.2 ms/step for vector (40.1× -speedup; the vector port follows TerraME's per-cell loops); the residual elevation divergence is floating-point rounding, not -algorithmic disagreement. +100% match for land use, soil, and elevation under tolerance (MAE 0.0011 m, max +error 0.024 m), with raster at 2.0 ms/step against 76.4 ms/step for vector (37.4× +speedup; the vector port follows TerraME's per-cell loops); the residual elevation +divergence is floating-point rounding, not algorithmic disagreement. **disslucc as a second case.** `disslucc` [@DisSLUCC], a package built on DisSModel, reimplements the LuccME demand, potential and allocation components (continuous CLUE-like From c253265442dcea3538d0524b6018046f6c8b7aad Mon Sep 17 00:00:00 2001 From: Sergio Costa Date: Wed, 7 Oct 2026 20:27:08 -0300 Subject: [PATCH 4/7] BR-MANGUE residuals, Mesa-Geo, remaining labs, spelling, AI disclosure, trim to 1700 words, final DOIs --- paper.bib | 24 +++-- paper.md | 306 +++++++++++++++++++++++------------------------------- 2 files changed, 148 insertions(+), 182 deletions(-) diff --git a/paper.bib b/paper.bib index 27b5c1c..1deca66 100644 --- a/paper.bib +++ b/paper.bib @@ -38,11 +38,10 @@ @incollection{Bezerra2025BM @software{Jordahl2021, author = {Kelsey Jordahl and Joris Van den Bossche and Martin Fleischmann and James McBride and Jacob Wasserman and others}, - title = {{geopandas/geopandas}: {v0.10.2}}, - month = oct, - year = {2021}, + title = {{geopandas/geopandas}}, + year = {2026}, publisher = {Zenodo}, - doi = {10.5281/zenodo.5573592} + doi = {10.5281/zenodo.2585848} } @@ -109,7 +108,7 @@ @software{BRMangue version = {0.3.0}, year = {2026}, publisher = {Zenodo}, - doi = {10.5281/zenodo.23220431}, + doi = {10.5281/zenodo.23223695}, url = {https://github.com/DisSModel/brmangue-dissmodel} } @@ -135,7 +134,7 @@ @software{DisSLUCC version = {0.5.0}, year = {2026}, publisher = {Zenodo}, - doi = {10.5281/zenodo.23219338}, + doi = {10.5281/zenodo.23224097}, url = {https://github.com/DisSModel/disslucc} } @@ -244,7 +243,8 @@ @inproceedings{Costa2009 author = {Costa, Sérgio Souza and Aguiar, Ana Paula Dutra and Câmara, Gilberto and Moreira, Evaldinolia}, booktitle = {Simpósio Brasileiro de Sensoriamento Remoto (SBSR)}, address = {Natal, RN, Brazil}, - year = {2009} + year = {2009}, + url = {https://www.researchgate.net/publication/228981638_Common_Concepts_to_Development_of_the_Top-Down_Models_of_Land_Changes} } @article{Verburg2002, @@ -271,6 +271,16 @@ @article{SoaresFilho2002 doi = {10.1016/S0304-3800(02)00059-5} } +@inproceedings{Wang2022, + title = {{Mesa-Geo}: A {GIS} Extension for the {Mesa} Agent-Based Modeling Framework in {Python}}, + author = {Wang, Boyu and Hess, Vincent and Crooks, Andrew}, + booktitle = {Proceedings of the 5th ACM SIGSPATIAL International Workshop on GeoSpatial Simulation (GeoSim 2022)}, + publisher = {ACM}, + pages = {1--10}, + year = {2022}, + doi = {10.1145/3557989.3566157} +} + @inproceedings{Kazil2020, title = {Utilizing {Python} for Agent-Based Modeling: The {Mesa} Framework}, author = {Kazil, Jackie and Masad, David and Crooks, Andrew}, diff --git a/paper.md b/paper.md index 4d23245..3b55aee 100644 --- a/paper.md +++ b/paper.md @@ -27,56 +27,49 @@ affiliations: city: São Luís state: MA country: Brazil -date: 24 September 2026 +date: 7 October 2026 bibliography: paper.bib --- ## Summary -DisSModel (Discrete Spatial Modeling) is a modular Python framework for spatially -explicit dynamic modeling, targeting the complexities of Land Use and Land Cover -Change (LUCC). It translates the modeling paradigms of the TerraME framework -[@Carneiro2013] into the Python ecosystem, enabling researchers to simulate -complex socio-environmental systems — forest fires, epidemiological spreads, -coastal dynamics — by coupling a time-stepped clock with the spatial data -structures of GeoPandas [@Jordahl2021]. +DisSModel (Discrete Spatial Modeling) is a modular Python framework for spatially explicit dynamic +modeling, targeting Land Use and Land Cover Change (LUCC). It translates the modeling paradigms of +TerraME [@Carneiro2013] into the Python ecosystem, enabling researchers to simulate socio-environmental +systems — forest fires, epidemics, coastal dynamics — by coupling a time-stepped clock with the +spatial data structures of GeoPandas [@Jordahl2021]. -The framework provides a **dual-substrate architecture**: a vector substrate -backed by GeoDataFrame for spatial expressiveness, and a raster substrate backed -by NumPy 2D arrays for high-performance vectorised computation. DisSModel is -available through the DisSModel GitHub organisation and on PyPI. +Its **dual-substrate architecture** pairs a vector substrate (GeoDataFrame) for spatial expressiveness +with a raster substrate (NumPy 2D arrays) for high-performance vectorized computation. DisSModel is +available through the DisSModel GitHub organization and on PyPI. ## Statement of Need -Python has become the lingua franca for geospatial data science, supported by -libraries such as GeoPandas and PySAL — but these tools target static analysis. -Dynamic spatial modeling, simulating how landscapes evolve over time, has -historically required specialised platforms. In Brazil, TerraME [@Carneiro2013] and -Dinamica EGO [@SoaresFilho2002; @SoaresFilho2013] are the most widely adopted general-purpose frameworks, while -institutions elsewhere rely on narrower allocation models such as CLUE and CLUE-S -[@Veldkamp1996; @Verburg2002]. This fragmentation leaves researchers choosing between a Lua-based +Python has become the lingua franca for geospatial data science, supported by libraries such as +GeoPandas and PySAL — but these tools target static analysis. Dynamic spatial modeling, simulating +how landscapes evolve over time, has historically required specialized platforms. In Brazil, TerraME +[@Carneiro2013] and Dinamica EGO [@SoaresFilho2002; @SoaresFilho2013] are the most widely adopted +general-purpose frameworks, while narrower allocation models such as CLUE and CLUE-S +[@Veldkamp1996; @Verburg2002] are used elsewhere. Researchers must choose between a Lua-based toolchain and single-purpose implementations with no shared contract. -While TerraME is conceptually robust, its reliance on Lua — a language with far -smaller adoption in data science than Python — creates a barrier for data -scientists, and the framework has seen no new release since August 2020. -General-purpose simulation libraries, meanwhile, lack native synchronisation -between a time-stepped clock and the geographical state of a GeoDataFrame. -DisSModel fills this gap with a lightweight scheduler coupled directly to vector -and raster spatial state, providing a Pythonic, actively maintained implementation -of the TerraME paradigm — and, through its satellite packages, of allocation -models like CLUE and CLUE-S. +TerraME is conceptually robust, but its reliance on Lua — far less common in data science than +Python — is a barrier, and the framework has seen no new release since August 2020. General-purpose +simulation libraries, meanwhile, lack native synchronization between a time-stepped clock and the +state of a GeoDataFrame. DisSModel fills this gap with a lightweight scheduler coupled to vector and +raster spatial state: a Pythonic, actively maintained implementation of the TerraME paradigm and, +through its satellite packages, of allocation models like CLUE and CLUE-S. Reproducibility is a first-class concern: the `executor` module provides a -standardised lifecycle — `validate → load → run → save` — capturing provenance +standardized lifecycle — `validate → load → run → save` — capturing provenance metadata (input checksums, parameters, timing, output paths) in an `ExperimentRecord` generated automatically for every run, with no additional -instrumentation by the modeller. +instrumentation by the modeler. ## State of the Field DisSModel occupies a niche between general-purpose agent-based modeling (ABM) -libraries and specialised GIS simulation software: +libraries and specialized GIS simulation software: | Aspect | TerraME | Dinamica EGO | DisSModel | |--------|---------|--------------|-----------| @@ -86,140 +79,105 @@ libraries and specialised GIS simulation software: | GIS Integration | TerraLib | Native Raster | GeoPandas / Rasterio | | Extensibility | Script-based | Block-based | Class Inheritance | | Reproducibility | Manual | Manual | Automated (ExperimentRecord) | -| Neighborhoods | GPM Support | Limited | libpysal weights (Queen, Rook, KNN, custom) | -NetLogo [@Wilensky1999] and Mesa [@Kazil2020] are excellent for ABM but require boilerplate to handle -real-world spatial projections. DisSModel uses GeoPandas as its core engine, -following the discrete spatial modeling approach of @SantosJunior2025. +NetLogo [@Wilensky1999] and Mesa [@Kazil2020] are excellent for ABM; Mesa-Geo [@Wang2022] adds GIS +data to Mesa, whereas DisSModel centers on cellular-space state with a synchronized clock and a +reproducible executor lifecycle. DisSModel builds on GeoPandas, following the discrete spatial modeling approach of @SantosJunior2025. ## Software Design -DisSModel is organised into five modules with strict separation of concerns, -extensible through class inheritance. **Core** manages the simulation clock: the -`Environment` orchestrates time progression, and spatial models auto-register at -instantiation, receiving ticks through `setup / pre_execute / execute / -post_execute` hooks. **Geo** provides the dual-substrate design: a vector -substrate (`SpatialModel`, `CellularAutomaton`) on GeoDataFrame with libpysal -neighbourhoods [@Rey2021], and a raster substrate (`RasterModel`, -`RasterCellularAutomaton`) on NumPy arrays with vectorised operations (`shift2d`, -`focal_sum`, `neighbor_contact`) replacing cell-by-cell loops. **Executor** defines -the `ModelExecutor` four-phase lifecycle (`validate`, `load`, `run`, `save`); -subclasses self-register via `__init_subclass__`, and every run produces an -`ExperimentRecord` with input checksum, parameters, timing, and output paths. -**IO** provides a unified dataset abstraction (`load_dataset` / `save_dataset`) -across GeoDataFrame, GeoTIFF, and Xarray/Zarr, with transparent `s3://` -resolution. **Visualization** integrates Matplotlib, Streamlit-compatible widgets, -and `RasterMap`. - -This extensibility has already produced independent domain packages: -`dissmodel-ca` [@DisSModelCA] (Cellular Automata patterns), `dissmodel-sysdyn` -[@DisSModelSysDyn] (System Dynamics), and `disslucc` [@DisSLUCC], which -implements LUCCME's continuous and discrete components — Demand, Potential, -and Allocation [@Veldkamp1996; @Verburg2002] — on the raster substrate and -the same `ModelExecutor` contract, an explicit Python counterpart to -TerraME/LuccME. +DisSModel is organized into five modules with strict separation of concerns, extensible through +class inheritance. **Core** manages the simulation clock: the `Environment` orchestrates time, and +spatial models auto-register at instantiation, receiving ticks through `setup / pre_execute / +execute / post_execute` hooks. **Geo** provides the dual-substrate design: a vector substrate +(`SpatialModel`, `CellularAutomaton`) on GeoDataFrame with libpysal neighborhoods [@Rey2021], and a +raster substrate (`RasterModel`, `RasterCellularAutomaton`) on NumPy arrays with vectorized +operations (`shift2d`, `focal_sum`, `neighbor_contact`) replacing cell-by-cell loops. **Executor** +defines the `ModelExecutor` four-phase lifecycle (`validate`, `load`, `run`, `save`); subclasses +self-register, and every run produces an `ExperimentRecord` with input checksum, parameters, timing, +and output paths. **IO** provides a unified dataset abstraction across GeoDataFrame, GeoTIFF, and +Xarray/Zarr, with transparent `s3://` resolution. **Visualization** integrates Matplotlib, +Streamlit-compatible widgets, and `RasterMap`. + +This extensibility has produced independent domain packages: `dissmodel-ca` [@DisSModelCA] +(Cellular Automata), `dissmodel-sysdyn` [@DisSModelSysDyn] (System Dynamics), and `disslucc` +[@DisSLUCC], which implements LuccME's continuous and discrete Demand, Potential, and Allocation +components [@Veldkamp1996; @Verburg2002] on the raster substrate and the same `ModelExecutor` +contract, an explicit Python counterpart to TerraME/LuccME. ## Validation and Performance -The vector substrate offers spatial expressiveness; the raster substrate enforces -vectorised rules over NumPy arrays. All benchmarks ran on an Intel Core -i7-7700T @ 2.90GHz, 15 GB RAM (Ubuntu, Python 3.12.3, NumPy 2.4.6, GeoPandas -1.1.3); absolute timings vary by hardware, but the relative speedup is the result -of interest. - -**Conway's Game of Life** confirms mathematical equivalence across substrates with -different throughput: - -| Grid | Cells | Raster, vectorised rule (ms/step) | Vector, per-cell `rule(idx)` (ms/step) | Speedup | -|-----:|------:|-----------------:|-----------------:|--------:| -| 10×10 | 100 | 0.12 | 74.81 | 639× | -| 50×50 | 2,500 | 0.19 | 1,707.76 | 8,809× | -| 100×100 | 10,000 | 0.41 | 7,069.14 | 17,394× | -| 200×200 | 40,000 | 1.21 | — | — | -| 500×500 | 250,000 | 9.74 | — | — | -| 1,000×1,000 | 1,000,000 | 30.60 | — | — | - -The speedup therefore measures a per-cell rule (one Python call per cell) against a -vectorised one, not the substrates themselves; vector runs above 10,000 cells were omitted. - -**BR-MANGUE coastal dynamics.** The foundation for coupled mangrove-flood modeling -was established by Bezerra et al. [@Bezerra2013] and extended in @Bezerra2025BM, -whose co-authors include Denilson da Silva Bezerra, Felipe Martins Sousa and the -submitting author — the same researchers responsible for the DisSModel reimplementation. The -`brmangue-dissmodel` package [@BRMangue] -validates the raster implementation against TerraME over the Maranhão Island -dataset (50,496 cells). In the baseline scenario (19 steps) land use and soil match -exactly at every checkpoint, and elevation matches on 97.4% of cells within 1 mm -(MAE 0.00038 m; maximum absolute error 0.10 m against elevations of 1–58 m); match -percentage is the appropriate metric for categorical outputs [@PontiusEtAl2011]. In the -flooding scenario (the laboratory parameters, 2,469 cells flooded by step 11) soil -matches exactly and land use differs in fewer than 0.05% of cells, with elevation within -1 mm on 94.9% of cells after 10 steps. The residual elevation differences are -floating-point rounding in the order of summation, not a difference in the rules. Both -scenarios are reproducible via the package's validation executor. - -Cross-substrate equivalence (60×60 synthetic grid, 3,600 cells, 10 steps) shows -100% match for land use, soil, and elevation under tolerance (MAE 0.0011 m, max -error 0.024 m), with raster at 2.0 ms/step against 76.4 ms/step for vector (37.4× -speedup; the vector port follows TerraME's per-cell loops); the residual elevation -divergence is floating-point rounding, not algorithmic disagreement. - -**disslucc as a second case.** `disslucc` [@DisSLUCC], a package built on DisSModel, -reimplements the LuccME demand, potential and allocation components (continuous CLUE-like -[@Veldkamp1996] and discrete CLUE-S-like). It is used here to test the `ModelExecutor` contract -and the raster substrate against a second TerraME application, not as a result of its own. Its -checks live in a separate, versioned benchmark [@DisSLUCCBenchmark] that compares every simulated -year, iteration counts included, with per-year outputs generated in a containerised TerraME -[@TerraMEDocker] and checked by SHA-256. Scenarios follow the LuccME test labs (`labNN`); the -`labNN_mdX` variants exercise the convergence loop. MAE suits fractional outputs -[@PontiusEtAl2011; @Willmott2005]. - -`lab01_md1643` (continuous, 6,574 cells, 6 steps) matches the reference with MAE = 0.0036 in the -final year (mean over years 0.0026, [0,1] scale). The residual is one deliberate deviation: -LuccME's per-cell correction (`correctCellChange`) never executes, because its guard reads a -field name that does not match the one defined, while `disslucc` runs it by default. Without it -(`cell_correction=False`) the match holds in every year, with identical iteration counts -(0, 0, 8, 26, 18, 17, 17; MAE < 1e-7). `lab15_md10` (discrete, 5,914 cells) reproduces the -reference cell for cell, with zero quantity and allocation disagreement [@PontiusMillones2011] -and identical iteration counts (0, 67, 56, 56, 61, 61); the final map alone only checks -coefficient transcription, and the iterations check the convergence loop. Overall, ten of the 21 -LuccME test labs and the two variants match with identical iteration counts and differences up to -3e-6 (single-precision paths). A validated lab runs in 0.1 to 0.5 s on the hardware above (median -of five; `make timing`), against 2 to 9 s for one uncontrolled TerraME run: informative, not a -speed ratio. +All benchmarks ran on an Intel Core i7-7700T @ 2.90GHz, 15 GB RAM (Ubuntu, Python 3.12.3, +NumPy 2.4.6, GeoPandas 1.1.3); absolute timings vary by hardware. + +**Conway's Game of Life** confirms equivalence across substrates: at 100×100 cells the vectorized +raster rule takes 0.41 ms/step against 7,069 ms/step for a per-cell vector rule, and the raster +scales to 10⁶ cells at 30.6 ms/step (per-cell versus vectorized rule). + +**BR-MANGUE coastal dynamics.** The coupled mangrove–flood model was established by +Bezerra et al. [@Bezerra2013] and extended in @Bezerra2025BM, co-authored by D.S.B., F.M.S. and the +submitting author, who are also responsible for the DisSModel reimplementation. +`brmangue-dissmodel` [@BRMangue] validates the raster implementation against TerraME over the +Maranhão Island dataset (50,496 cells). In the baseline scenario (19 steps) land use and soil match +exactly at every checkpoint and elevation matches on 97.4% of cells within 1 mm (MAE 0.00038 m; +maximum error 0.10 m); match percentage suits categorical outputs +[@PontiusEtAl2011]. In the flooding scenario (laboratory parameters) TerraME floods 2,469 non-sea +cells by step 11 and the Python model 2,467; soil matches exactly, land use differs in 4 cells +(0.008%), and elevation matches on 94.4% of cells (MAE 0.008 m, maximum error 1.0 m). The residuals +come from exact ties in elevation: the flux rule compares accumulated elevations with `<=`, so a +~1e-16 difference in summation order (sequential in TerraME, per direction in NumPy) can flip a +comparison and, near the flooding threshold, a cell's class. They are floating-point effects, not a +difference in the rules. Both are reproducible with its validation executor. + +Cross-substrate equivalence (60×60 synthetic grid, 10 steps) gives 100% match for land use, soil +and elevation under tolerance (MAE 0.0011 m, max 0.024 m; floating-point rounding, not algorithmic +disagreement), with raster at 2.0 ms/step against 76.4 ms/step for vector (37.4×; the vector port +follows TerraME's per-cell loops). + +**disslucc as a second case.** `disslucc` [@DisSLUCC], built on DisSModel, reimplements the LuccME +demand, potential and allocation components (continuous CLUE-like [@Veldkamp1996] and discrete +CLUE-S-like). It tests the `ModelExecutor` contract and the raster substrate against a second +TerraME application, not as a result in itself. Its checks live in a separate, versioned benchmark +[@DisSLUCCBenchmark] that compares every simulated year, iteration counts included, with per-year +outputs generated in a containerized TerraME [@TerraMEDocker] and checked by SHA-256. Scenarios +follow the LuccME test labs (`labNN`); the `labNN_mdX` variants exercise the convergence loop. MAE +suits fractional outputs [@PontiusEtAl2011; @Willmott2005]. + +`lab01_md1643` (continuous, 6,574 cells, 2008–2014) matches the reference with MAE = 0.0036 in the +final year ([0,1] scale). The residual is one deliberate deviation: LuccME's per-cell correction +(`correctCellChange`) never executes, because its guard reads a field name that does not match the +one defined, while `disslucc` runs it by default. Without it (`cell_correction=False`) the match +holds in every year, with identical iteration counts (MAE < 1e-7). +`lab15_md10` (discrete, 5,914 cells) reproduces the reference cell for cell, with zero quantity and +allocation disagreement [@PontiusMillones2011] and identical iteration counts. Overall, ten of 21 LuccME test labs and both variants match with identical iteration +counts and differences up to 3e-6 (single precision); a validated lab runs in 0.1 to 0.5 s on +the hardware above (median of five; `make timing`). The other eleven labs need potential and +allocation components not yet implemented; student fellows are developing them, and each lab joins +the benchmark as its components land. ## Research Impact Statement -DisSModel's scientific lineage is rooted in the TerraME/LuccME research program at -INPE. The submitting author conducted doctoral research at INPE under Prof. -Gilberto Câmara and Dr. Ana Paula Dutra Aguiar — principal architects of -TerraME/LuccME — and has co-authored the modeling program since 2009 -[@Moreira2009; @Costa2009]; `disslucc` reimplements in Python the -continuous and discrete allocation components of that lineage [@LuccME]. On -7 May 2026, DisSModel was presented at INPE's Graduate Program in Applied -Computing seminar series (recording: https://youtu.be/o7pMJt0CvXU). - -The framework is in active use across two UFMA research groups. Within LambdaGeo, -`brmangue-dissmodel` builds on a Master's student's reference implementation. Independently, Prof. Denilson da Silva Bezerra (UFMA, former -INPE), whose doctoral work established BR-MANGUE's scientific foundation -[@Bezerra2013], uses the DisSModel reimplementation in his own coastal dynamics -program (UFMA projects PVCBS4959-2025 and PVCBS4960-2025), a -collaboration predating DisSModel itself [@Bezerra2025BM]. - -Since September 2026, four undergraduate research fellows, funded by UFMA and by CNPq, -are being trained on the project. The 2026 development effort prepared for this by stabilizing -the `ModelExecutor` contract, so that each fellow can own an independent repository — -`disslucc`, `brmangue-dissmodel`, or `disscube` [@DisSCube] (a data-cube layer, a Python alternative to -TerraME's `fillCellularSpace`) — without core changes. - -Studies such as @Bezerra2022, developed using LuccME, are the class -of models `disslucc` aims to reproduce. A roadmap toward -DisSModel 1.0 (May 2027) anchors community outreach including an open textbook, -*Geospatial Modeling with Python* -(https://lambdageo.github.io/geospatial-modeling-python/), already in progress. -This positions DisSModel as the simulation layer in the Brazilian Earth -Observation stack, complementary to SITS [@Simoes2021] and the Brazil Data Cube -[@Ferreira2020]. +DisSModel's scientific lineage is rooted in the TerraME/LuccME research program at INPE. The +submitting author conducted doctoral research there under Prof. Gilberto Câmara and Dr. Ana Paula +Dutra Aguiar — principal architects of TerraME/LuccME — and has co-authored the modeling program +since 2009 [@Moreira2009; @Costa2009]; `disslucc` reimplements in Python the continuous and +discrete allocation components of that lineage [@LuccME]. + +The framework is in use across two UFMA research groups. Within LambdaGeo, `brmangue-dissmodel` +builds on the reference implementation by co-author F.M.S. Independently, Prof. Denilson da Silva +Bezerra (UFMA, former INPE), whose doctoral work founded BR-MANGUE [@Bezerra2013], uses the DisSModel reimplementation in his own coastal dynamics program (UFMA +projects PVCBS4959-2025 and PVCBS4960-2025), a collaboration predating DisSModel itself +[@Bezerra2025BM]. + +Since September 2026, four undergraduate research fellows (UFMA, CNPq) are being trained on the +project; the stabilized `ModelExecutor` contract lets each own an independent repository — +`disslucc`, `brmangue-dissmodel`, or `disscube` [@DisSCube] (a data-cube layer, a Python alternative +to TerraME's `fillCellularSpace`) — without core changes. + +A roadmap toward DisSModel 1.0 (May 2027) includes an open textbook, *Geospatial Modeling with +Python* (https://lambdageo.github.io/geospatial-modeling-python/), already in progress. This +positions DisSModel as a candidate simulation layer in the Brazilian Earth Observation stack, +complementary to SITS [@Simoes2021] and the Brazil Data Cube [@Ferreira2020]. ## Author Contributions @@ -238,25 +196,23 @@ We thank José Magno Pinheiro Alves for early validation testing. ## AI Usage Disclosure -Development followed several phases. The initial prototype (May–June 2025), -corresponding to the second author's undergraduate thesis [@SantosJunior2025], did -not involve generative AI. Development resumed in February–March 2026 with Claude -(chat) used mainly for documentation; from April 2026, Gemini CLI accelerated code -generation and refactoring; from June 2026, Claude Code (CLI) was used on newer -satellite repositories such as `disslucc`, including the audit of the -validation routines against the original TerraME scripts. In September–October 2026, -in response to the review, Claude (Claude Code and chat) was also used to build the -separate `disslucc-benchmark` repository (scenario definitions, the comparison and -timing scripts, and a differential test against the original Lua code), to reorganize -`disslucc`, and to revise the validation text of this paper so that it matches the -benchmark; the reference results themselves come from the original TerraME/LuccME -code, run unmodified in a container. AI tools also assisted -with writing in English, not the submitting author's native language. The -scientific design — the TerraME compatibility contract, executor pattern, -dual-substrate architecture, and validation methodology — predates and is -independent of this AI-assisted phase, tracing to the submitting author's doctoral -research at INPE and the undergraduate thesis cited above. AI assisted with -implementation velocity and language clarity, not scientific or architectural -decisions. All outputs were reviewed and validated by the authors. +Development followed several phases. The initial prototype (May–June 2025), the second author's +undergraduate thesis [@SantosJunior2025], did not involve generative AI. From February 2026 Claude +(chat) was used for documentation, from April Gemini CLI for code generation and refactoring, and +from June Claude Code (CLI) on satellite repositories such as `disslucc`, including auditing its +validation routines against the original TerraME scripts. In +September–October 2026, in response to the review, Claude (Claude Code and chat) wrote and modified +code and text: the `disslucc-benchmark` repository (scenarios, comparison and timing scripts, a +differential test against the original Lua code); the reorganization of `disslucc`; in +`brmangue-dissmodel`, the diagnosis and correction of two discrepancies with TerraME (neighbor +counting at borders; the snapshot shared by the flood and mangrove models) with tests, a headless +driver for regenerating TerraME outputs, and documentation; and the revision of this paper's +validation text. The reference results come from the original TerraME/LuccME code run unmodified in +a container (for BR-MANGUE, unmodified model files with a new headless driver), so they do not +depend on AI-written code. AI also assisted with English writing. The scientific design — TerraME +compatibility contract, executor pattern, dual-substrate architecture, validation methodology — +predates this phase and traces to the submitting author's doctoral research at INPE. The authors +made the design decisions and chose the validation criteria; AI-generated code and text were +reviewed, tested, and run by the authors. ## References From e02c013617d522166d05ff761205669bcce254f9 Mon Sep 17 00:00:00 2001 From: Sergio Costa Date: Wed, 7 Oct 2026 21:21:11 -0300 Subject: [PATCH 5/7] docs(paper): AI disclosure for the BR-MANGUE driver, tie validation numbers to v0.3.0, step 11, Game of Life wording --- paper.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/paper.md b/paper.md index 3b55aee..9b8dc93 100644 --- a/paper.md +++ b/paper.md @@ -110,28 +110,27 @@ contract, an explicit Python counterpart to TerraME/LuccME. All benchmarks ran on an Intel Core i7-7700T @ 2.90GHz, 15 GB RAM (Ubuntu, Python 3.12.3, NumPy 2.4.6, GeoPandas 1.1.3); absolute timings vary by hardware. -**Conway's Game of Life** confirms equivalence across substrates: at 100×100 cells the vectorized +**Conway's Game of Life** compares the two substrates: at 100×100 cells the vectorized raster rule takes 0.41 ms/step against 7,069 ms/step for a per-cell vector rule, and the raster -scales to 10⁶ cells at 30.6 ms/step (per-cell versus vectorized rule). +scales to 10⁶ cells at 30.6 ms/step. **BR-MANGUE coastal dynamics.** The coupled mangrove–flood model was established by Bezerra et al. [@Bezerra2013] and extended in @Bezerra2025BM, co-authored by D.S.B., F.M.S. and the submitting author, who are also responsible for the DisSModel reimplementation. `brmangue-dissmodel` [@BRMangue] validates the raster implementation against TerraME over the -Maranhão Island dataset (50,496 cells). In the baseline scenario (19 steps) land use and soil match +Maranhão Island dataset (50,496 cells); figures are for v0.3.0, after fixing border neighbor counting and the shared flood/mangrove snapshot. In the baseline scenario (19 steps) land use and soil match exactly at every checkpoint and elevation matches on 97.4% of cells within 1 mm (MAE 0.00038 m; maximum error 0.10 m); match percentage suits categorical outputs [@PontiusEtAl2011]. In the flooding scenario (laboratory parameters) TerraME floods 2,469 non-sea cells by step 11 and the Python model 2,467; soil matches exactly, land use differs in 4 cells -(0.008%), and elevation matches on 94.4% of cells (MAE 0.008 m, maximum error 1.0 m). The residuals +(0.008%), and at step 11 elevation matches on 94.4% of cells (MAE 0.008 m, maximum error 1.0 m). The residuals come from exact ties in elevation: the flux rule compares accumulated elevations with `<=`, so a ~1e-16 difference in summation order (sequential in TerraME, per direction in NumPy) can flip a comparison and, near the flooding threshold, a cell's class. They are floating-point effects, not a -difference in the rules. Both are reproducible with its validation executor. +difference in the rules; both scenarios are reproducible with the validation executor. Cross-substrate equivalence (60×60 synthetic grid, 10 steps) gives 100% match for land use, soil -and elevation under tolerance (MAE 0.0011 m, max 0.024 m; floating-point rounding, not algorithmic -disagreement), with raster at 2.0 ms/step against 76.4 ms/step for vector (37.4×; the vector port +and elevation under tolerance (MAE 0.0011 m, max 0.024 m; floating-point rounding), with raster at 2.0 ms/step against 76.4 ms/step for vector (37.4×; the vector port follows TerraME's per-cell loops). **disslucc as a second case.** `disslucc` [@DisSLUCC], built on DisSModel, reimplements the LuccME @@ -206,13 +205,12 @@ code and text: the `disslucc-benchmark` repository (scenarios, comparison and ti differential test against the original Lua code); the reorganization of `disslucc`; in `brmangue-dissmodel`, the diagnosis and correction of two discrepancies with TerraME (neighbor counting at borders; the snapshot shared by the flood and mangrove models) with tests, a headless -driver for regenerating TerraME outputs, and documentation; and the revision of this paper's -validation text. The reference results come from the original TerraME/LuccME code run unmodified in -a container (for BR-MANGUE, unmodified model files with a new headless driver), so they do not -depend on AI-written code. AI also assisted with English writing. The scientific design — TerraME +driver for regenerating TerraME outputs, and documentation; and this paper's validation text. The reference results come from the original TerraME/LuccME code run unmodified in +a container; the reference model files are unmodified and, for BR-MANGUE, only the headless +driver that runs them is AI-written. AI also assisted with English writing. The scientific design — TerraME compatibility contract, executor pattern, dual-substrate architecture, validation methodology — predates this phase and traces to the submitting author's doctoral research at INPE. The authors -made the design decisions and chose the validation criteria; AI-generated code and text were -reviewed, tested, and run by the authors. +made the design decisions and chose the validation criteria, and reviewed, tested and ran all +AI-generated code and text. ## References From c0c365a11d1bd084f621662060a387b403de6463 Mon Sep 17 00:00:00 2001 From: Sergio Costa Date: Wed, 7 Oct 2026 22:24:50 -0300 Subject: [PATCH 6/7] docs(paper): final revision for JOSS review - BR-MANGUE validation against TerraME (baseline and flooding scenarios), tied to brmangue-dissmodel v0.3.0 - Mesa-Geo in the state of the field; remaining labs explained - AI usage disclosure rewritten (scope, phases, validation references) - INPE seminar (7 May 2026) in the research impact - paper.bib: final Zenodo DOIs (disslucc, brmangue-dissmodel, disslucc-benchmark 0.2.2), Costa2009 URL, seminar entry --- paper.bib | 16 +++++++++++++--- paper.md | 31 ++++++++++++------------------- 2 files changed, 25 insertions(+), 22 deletions(-) diff --git a/paper.bib b/paper.bib index 1deca66..85fad66 100644 --- a/paper.bib +++ b/paper.bib @@ -134,7 +134,7 @@ @software{DisSLUCC version = {0.5.0}, year = {2026}, publisher = {Zenodo}, - doi = {10.5281/zenodo.23224097}, + doi = {10.5281/zenodo.23219338}, url = {https://github.com/DisSModel/disslucc} } @@ -148,13 +148,13 @@ @software{DisSCube url = {https://github.com/DisSModel/disscube} } -% TODO: if a v0.2.0 release is made before the paper is final, add its version and DOI here. @software{DisSLUCCBenchmark, author = {Costa, Sérgio Souza}, title = {{disslucc-benchmark}: Reproducible validation of {disslucc} against the {LuccME} 3.1 labs}, + version = {0.2.2}, year = {2026}, publisher = {Zenodo}, - doi = {10.5281/zenodo.23169808}, + doi = {10.5281/zenodo.23224097}, url = {https://github.com/LambdaGeo/disslucc-benchmark} } @@ -311,3 +311,13 @@ @article{SoaresFilho2013 pages = {80--87}, doi = {10.1016/j.envsoft.2013.01.010} } + +@misc{Costa2026INPE, + author = {Costa, Sérgio Souza}, + title = {Building Open and Reproducible Geospatial Simulations with {Python}}, + howpublished = {Seminar at INPE (remote), recorded on the INPE program's YouTube channel}, + year = {2026}, + month = may, + url = {https://lambdageo.github.io/presentations/2026-05-07-inpe-seminar/}, + note = {Video: \url{https://www.youtube.com/watch?v=o7pMJt0CvXU}} +} diff --git a/paper.md b/paper.md index 9b8dc93..a0900a3 100644 --- a/paper.md +++ b/paper.md @@ -118,7 +118,7 @@ scales to 10⁶ cells at 30.6 ms/step. Bezerra et al. [@Bezerra2013] and extended in @Bezerra2025BM, co-authored by D.S.B., F.M.S. and the submitting author, who are also responsible for the DisSModel reimplementation. `brmangue-dissmodel` [@BRMangue] validates the raster implementation against TerraME over the -Maranhão Island dataset (50,496 cells); figures are for v0.3.0, after fixing border neighbor counting and the shared flood/mangrove snapshot. In the baseline scenario (19 steps) land use and soil match +Maranhão Island dataset (50,496 cells); figures are for v0.3.0, after fixing, in `brmangue-dissmodel`, border neighbor counting and the shared flood/mangrove snapshot. In the baseline scenario (19 steps) land use and soil match exactly at every checkpoint and elevation matches on 97.4% of cells within 1 mm (MAE 0.00038 m; maximum error 0.10 m); match percentage suits categorical outputs [@PontiusEtAl2011]. In the flooding scenario (laboratory parameters) TerraME floods 2,469 non-sea @@ -160,7 +160,8 @@ DisSModel's scientific lineage is rooted in the TerraME/LuccME research program submitting author conducted doctoral research there under Prof. Gilberto Câmara and Dr. Ana Paula Dutra Aguiar — principal architects of TerraME/LuccME — and has co-authored the modeling program since 2009 [@Moreira2009; @Costa2009]; `disslucc` reimplements in Python the continuous and -discrete allocation components of that lineage [@LuccME]. +discrete allocation components of that lineage [@LuccME]. DisSModel was presented at a seminar of INPE's Applied Computing graduate program (CAP) on 7 May +2026 [@Costa2026INPE]. The framework is in use across two UFMA research groups. Within LambdaGeo, `brmangue-dissmodel` builds on the reference implementation by co-author F.M.S. Independently, Prof. Denilson da Silva @@ -195,22 +196,14 @@ We thank José Magno Pinheiro Alves for early validation testing. ## AI Usage Disclosure -Development followed several phases. The initial prototype (May–June 2025), the second author's -undergraduate thesis [@SantosJunior2025], did not involve generative AI. From February 2026 Claude -(chat) was used for documentation, from April Gemini CLI for code generation and refactoring, and -from June Claude Code (CLI) on satellite repositories such as `disslucc`, including auditing its -validation routines against the original TerraME scripts. In -September–October 2026, in response to the review, Claude (Claude Code and chat) wrote and modified -code and text: the `disslucc-benchmark` repository (scenarios, comparison and timing scripts, a -differential test against the original Lua code); the reorganization of `disslucc`; in -`brmangue-dissmodel`, the diagnosis and correction of two discrepancies with TerraME (neighbor -counting at borders; the snapshot shared by the flood and mangrove models) with tests, a headless -driver for regenerating TerraME outputs, and documentation; and this paper's validation text. The reference results come from the original TerraME/LuccME code run unmodified in -a container; the reference model files are unmodified and, for BR-MANGUE, only the headless -driver that runs them is AI-written. AI also assisted with English writing. The scientific design — TerraME -compatibility contract, executor pattern, dual-substrate architecture, validation methodology — -predates this phase and traces to the submitting author's doctoral research at INPE. The authors -made the design decisions and chose the validation criteria, and reviewed, tested and ran all -AI-generated code and text. +The initial prototype (May–June 2025), the second author's undergraduate thesis +[@SantosJunior2025], did not involve generative AI. From February 2026, Claude and Gemini CLI +supported documentation, tests and refactoring of code that already existed. Since mid-2026, +Claude Code has been used across the whole ecosystem (the core framework, its satellite packages +and their benchmarks) for implementation, validation scripts, documentation and this paper's text +and English. This is what has made it feasible to build the ecosystem envisioned by the +submitting author. The reference outputs used in validation come from the unmodified TerraME/LuccME model files run in a container; for BR-MANGUE, only the headless driver that runs them is AI-written. The scientific design — TerraME compatibility contract, executor pattern, +dual-substrate architecture, validation methodology — is the authors', and traces to the +submitting author's doctoral research at INPE. The authors reviewed, tested and ran all AI-generated code and text. ## References From 2e8e3aff15c43ec95fe99c33f34c0a064e574a24 Mon Sep 17 00:00:00 2001 From: Sergio Costa Date: Wed, 7 Oct 2026 22:33:33 -0300 Subject: [PATCH 7/7] docs(paper): final revision for JOSS review --- paper.bib | 17 +---------------- paper.md | 23 ++++++++++++----------- 2 files changed, 13 insertions(+), 27 deletions(-) diff --git a/paper.bib b/paper.bib index 85fad66..d101612 100644 --- a/paper.bib +++ b/paper.bib @@ -45,21 +45,6 @@ @software{Jordahl2021 } -@article{Bezerra2022, - title = {New land-use change scenarios for Brazil: Refining global SSPs with a regional spatially-explicit allocation model}, - author = {Bezerra, Francisco Gilney Silva and Von Randow, Celso and - Assis, Talita Oliveira and Bezerra, Karine Rocha Aguiar and - Tejada, Graciela and Castro, Aline Anderson and - Gomes, Diego Melo de Paula and Avancini, Rodrigo and - Aguiar, Ana Paula}, - journal = {PLOS ONE}, - volume = {17}, - number = {4}, - pages = {e0256052}, - year = {2022}, - doi = {10.1371/journal.pone.0256052} -} - @mastersthesis{SantosJunior2025, title = {Discrete Spatial Modeling: Uma proposta de arcabouço para construção de modelos dinâmicos espacialmente explícitos baseado no ecossistema Python}, author = {Santos Junior, Nerval de Jesus}, @@ -320,4 +305,4 @@ @misc{Costa2026INPE month = may, url = {https://lambdageo.github.io/presentations/2026-05-07-inpe-seminar/}, note = {Video: \url{https://www.youtube.com/watch?v=o7pMJt0CvXU}} -} +} \ No newline at end of file diff --git a/paper.md b/paper.md index a0900a3..38a2773 100644 --- a/paper.md +++ b/paper.md @@ -110,18 +110,19 @@ contract, an explicit Python counterpart to TerraME/LuccME. All benchmarks ran on an Intel Core i7-7700T @ 2.90GHz, 15 GB RAM (Ubuntu, Python 3.12.3, NumPy 2.4.6, GeoPandas 1.1.3); absolute timings vary by hardware. -**Conway's Game of Life** compares the two substrates: at 100×100 cells the vectorized -raster rule takes 0.41 ms/step against 7,069 ms/step for a per-cell vector rule, and the raster -scales to 10⁶ cells at 30.6 ms/step. +**Conway's Game of Life** compares the two substrates with the same rule and initial state. The +vector rule is a per-cell Python method querying libpysal Queen neighbors; the raster rule is one +whole-grid focal sum; final states are compared cell by cell. At 100×100 cells the raster takes +0.41 ms/step against 7,069 ms/step for the vector (a gap that reflects the per-cell style of the +vector API) and scales to 10⁶ cells at 30.6 ms/step. **BR-MANGUE coastal dynamics.** The coupled mangrove–flood model was established by Bezerra et al. [@Bezerra2013] and extended in @Bezerra2025BM, co-authored by D.S.B., F.M.S. and the submitting author, who are also responsible for the DisSModel reimplementation. `brmangue-dissmodel` [@BRMangue] validates the raster implementation against TerraME over the -Maranhão Island dataset (50,496 cells); figures are for v0.3.0, after fixing, in `brmangue-dissmodel`, border neighbor counting and the shared flood/mangrove snapshot. In the baseline scenario (19 steps) land use and soil match +Maranhão Island dataset (50,496 cells); figures refer to `brmangue-dissmodel` v0.3.0, which fixed border neighbor counting and the shared flood/mangrove snapshot. Match percentage suits categorical outputs [@PontiusEtAl2011]. In the baseline scenario (19 steps) land use and soil match exactly at every checkpoint and elevation matches on 97.4% of cells within 1 mm (MAE 0.00038 m; -maximum error 0.10 m); match percentage suits categorical outputs -[@PontiusEtAl2011]. In the flooding scenario (laboratory parameters) TerraME floods 2,469 non-sea +maximum error 0.10 m). In the flooding scenario (laboratory parameters) TerraME floods 2,469 non-sea cells by step 11 and the Python model 2,467; soil matches exactly, land use differs in 4 cells (0.008%), and at step 11 elevation matches on 94.4% of cells (MAE 0.008 m, maximum error 1.0 m). The residuals come from exact ties in elevation: the flux rule compares accumulated elevations with `<=`, so a @@ -164,10 +165,10 @@ discrete allocation components of that lineage [@LuccME]. DisSModel was presente 2026 [@Costa2026INPE]. The framework is in use across two UFMA research groups. Within LambdaGeo, `brmangue-dissmodel` -builds on the reference implementation by co-author F.M.S. Independently, Prof. Denilson da Silva -Bezerra (UFMA, former INPE), whose doctoral work founded BR-MANGUE [@Bezerra2013], uses the DisSModel reimplementation in his own coastal dynamics program (UFMA -projects PVCBS4959-2025 and PVCBS4960-2025), a collaboration predating DisSModel itself -[@Bezerra2025BM]. +builds on the reference implementation by co-author F.M.S. Co-author D.S.B. (UFMA, former INPE), +whose doctoral work founded BR-MANGUE [@Bezerra2013], also adopts the DisSModel reimplementation in +his coastal dynamics projects (UFMA PVCBS4959-2025 and PVCBS4960-2025), a collaboration predating +DisSModel itself [@Bezerra2025BM]. Since September 2026, four undergraduate research fellows (UFMA, CNPq) are being trained on the project; the stabilized `ModelExecutor` contract lets each own an independent repository — @@ -206,4 +207,4 @@ submitting author. The reference outputs used in validation come from the unmodi dual-substrate architecture, validation methodology — is the authors', and traces to the submitting author's doctoral research at INPE. The authors reviewed, tested and ran all AI-generated code and text. -## References +## References \ No newline at end of file