From 2cb1928c748d9373a949bb0342736f181117e5e9 Mon Sep 17 00:00:00 2001 From: Sergio Souza Costa Date: Fri, 12 Jun 2026 08:45:54 -0300 Subject: [PATCH 1/4] doc(readme): scope README to the core package and add DisSModel Platform roadmap note The README described features that live in the separate DisSModel Platform project (REST reproduce endpoint, Docker/FastAPI/Redis deployment), which could mislead users and reviewers of the published package. - Rewrite the 'Cloud-ready' feature bullet as 'Platform-ready contract', linking to the new roadmap section - Replace the curl /reproduce example with a description of what the locally generated record.json actually provides - Add a 'Roadmap: DisSModel Platform' section stating explicitly that the platform is a separate project under development and not part of this package Co-Authored-By: Claude Fable 5 --- README.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index c7a2e35..d4847a8 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ DisSModel is the synthesis: a Python-native, FAIR-aligned, cloud-ready simulatio - **Executor pattern** — strict separation between science (models) and infrastructure (I/O, CLI, reproducible execution). - **Experiment tracking** — every run generates an immutable `ExperimentRecord` with SHA-256 checksums, TOML snapshot, and full provenance. - **Storage-agnostic I/O** — `dissmodel.io` handles local paths and `s3://` URIs transparently. -- **Cloud-ready** — deploy via Docker, FastAPI, and Redis without changing model code. +- **Platform-ready contract** — the `ModelExecutor` interface is designed so the same model code can later run on the [DisSModel Platform](#-roadmap-dissmodel-platform), a separate project under development. --- @@ -189,12 +189,9 @@ Every run produces an immutable provenance record: } ``` -Reproduce any past experiment exactly: - -```bash -curl -X POST http://localhost:8000/experiments/abc123/reproduce \ - -H "X-API-Key: chave-sergio" -``` +The `record.json` written next to every output contains everything needed to +re-run the experiment: the input URI and its SHA-256 checksum, the resolved +parameters (TOML + CLI overrides), per-phase timings, and the output checksum. --- @@ -236,6 +233,19 @@ Each repository demonstrates how to: --- +## 🔭 Roadmap: DisSModel Platform + +The **DisSModel Platform** is a distributed execution environment (FastAPI, +Redis, Docker, MinIO/S3) currently under development as a **separate project**. +It consumes the same `ModelExecutor` contract documented above — executors run +through its job queue without any change to their scientific code, including +remote experiment reproduction from a stored `ExperimentRecord`. + +**The platform is not part of this package.** Everything described in this +README works locally with `pip install dissmodel` alone. + +--- + ## 📚 Documentation - 📘 **User Guide**: [https://dissmodel.github.io/dissmodel/](https://dissmodel.github.io/dissmodel/) From 1b1d1dfb105c3a86e3824da7dc07166df4d5fde7 Mon Sep 17 00:00:00 2001 From: Sergio Souza Costa Date: Fri, 12 Jun 2026 08:54:05 -0300 Subject: [PATCH 2/4] doc(paper): align claims with the core package capabilities - Replace the 'Anisotropy / GPM Support' row in the comparison table: DisSModel provides neighborhood definition via libpysal spatial weights (Queen, Rook, KNN, custom adjacency), not a GPM implementation - Remove the runtime 'TOML-based model registry' claim from the executor description (platform-side feature); keep what the package provides: executors as standard Python packages with parameters resolved from a version-controllable TOML specification - Clarify that Streamlit dashboards live in the satellite packages; the core ships Streamlit-compatible input widgets - Mark the DisSModel Platform explicitly as a separate project in the Research Impact section Co-Authored-By: Claude Fable 5 --- paper.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/paper.md b/paper.md index a20e929..3409efd 100644 --- a/paper.md +++ b/paper.md @@ -94,7 +94,7 @@ its positioning: | GIS Integration | TerraLib | Native Raster | GeoPandas / Rasterio | | Extensibility | Script-based | Block-based | Class Inheritance | | Reproducibility | Manual | Manual | Automated (ExperimentRecord) | -| Anisotropy | GPM Support | Limited | GPM Support | +| Neighborhoods | GPM Support | Limited | libpysal weights (Queen, Rook, KNN, custom) | While frameworks like **NetLogo** and **Mesa** are excellent for ABM, they often require significant boilerplate to handle real-world spatial projections. DisSModel @@ -126,10 +126,8 @@ lifecycle — `validate`, `load`, `run`, `save` — that the framework orchestra `ExecutorRegistry` through Python's `__init_subclass__` mechanism, requiring no boilerplate. Every execution produces an `ExperimentRecord` Pydantic object capturing the input URI, SHA-256 checksum, resolved parameters, per-phase timing, output path, -and free-form logs. Executors are distributed as standard Python packages and -resolved at runtime from a TOML-based model registry, enabling institutional -governance of calibrated model configurations through version-controlled pull -requests. +and free-form logs. Executors are distributed as standard Python packages, with run +parameters resolved from a version-controllable TOML specification. **IO** provides a unified dataset abstraction (`load_dataset` / `save_dataset`) that detects format automatically and dispatches to the appropriate backend — @@ -137,9 +135,10 @@ GeoDataFrame, rasterio GeoTIFF, or Xarray/Zarr — based on file extension or an explicit `fmt` argument. For cloud deployments, the same API resolves `s3://` URIs transparently via the configured MinIO/S3 client. -**Visualization** integrates Matplotlib for static outputs, Streamlit for -interactive dashboards, and `RasterMap` for step-by-step raster rendering in both -headless and interactive modes. +**Visualization** integrates Matplotlib for static outputs, Streamlit-compatible +input widgets (interactive dashboards are provided by the satellite packages), and +`RasterMap` for step-by-step raster rendering in both headless and interactive +modes. The extensibility of DisSModel's class hierarchy has already produced domain packages distributed as independent Python packages through the DisSModel GitHub @@ -235,7 +234,7 @@ The emergence of independent domain packages — `dissmodel-ca`, `dissmodel-sysd `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 +Platform, a separate 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 From e27c74a873023f0496f000200e0c38e2fb07efa8 Mon Sep 17 00:00:00 2001 From: Sergio Souza Costa Date: Fri, 12 Jun 2026 09:12:09 -0300 Subject: [PATCH 3/4] doc: replace coastal-dynamics with brmangue-dissmodel and refresh benchmark results MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BR-MANGUE now lives in the brmangue-dissmodel package, which holds both the raster and vector substrates plus two validation levels (raster vs TerraME and vector vs raster). coastal-dynamics is being retired. - paper: cite brmangue-dissmodel (@BRMangue) instead of @CoastalDynamics; describe the two-level validation — raster vs TerraME on the Maranhão Island dataset (50,496 cells, 20 steps: uso 99.90%, solo 99.85%, alt 90.67% within 1 mm) and vector vs raster on the 60x60 synthetic grid (10 steps, 100% match on all bands, raster 5.0 ms/step vs vector 124.4 ms/step) - paper: refresh Game of Life benchmark table with current measurements (1M cells at ~27 ms/step) - paper.bib: replace the CoastalDynamics entry with BRMangue - README and docs/examples.md: point the ecosystem tables to brmangue-dissmodel (install verified via pip git+ and smoke imports) Co-Authored-By: Claude Fable 5 --- README.md | 4 ++-- docs/examples.md | 4 ++-- paper.bib | 8 ++++---- paper.md | 51 ++++++++++++++++++++++++++++-------------------- 4 files changed, 38 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index d4847a8..9e2f061 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ DisSModel is the synthesis: a Python-native, FAIR-aligned, cloud-ready simulatio |--------------------------|---------------------|------| | **TerraME** | `dissmodel` | Generic framework for dynamic spatial modeling | | **LUCCME** | `DisSLUCC` | LUCC domain models built on dissmodel | -| — | `coastal-dynamics` | Coastal domain models built on dissmodel | +| — | `brmangue-dissmodel` | Coastal domain models (BR-MANGUE) built on dissmodel | | **TerraLib** | `geopandas` / `rasterio` | Geographic data handling | --- @@ -220,7 +220,7 @@ DisSModel is a core framework. To maintain a clean and specialized environment, |------------|-------------|---------| | [`dissmodel-ca`](https://github.com/DisSModel/dissmodel-ca) | Classic Cellular Automata (Game of Life, Forest Fire, Growth) | `pip install "git+https://github.com/DisSModel/dissmodel-ca.git"` | | [`dissmodel-sysdyn`](https://github.com/DisSModel/dissmodel-sysdyn) | System Dynamics (SIR, Predator-Prey, Lorenz) | `pip install "git+https://github.com/DisSModel/dissmodel-sysdyn.git"` | -| [`coastal-dynamics`](https://github.com/DisSModel/coastal-dynamics) | Coastal flooding and mangrove succession models | `pip install "git+https://github.com/DisSModel/coastal-dynamics.git"` | +| [`brmangue-dissmodel`](https://github.com/DisSModel/brmangue-dissmodel) | BR-MANGUE coastal flooding and mangrove succession model (raster + vector, validated against TerraME) | `pip install "git+https://github.com/DisSModel/brmangue-dissmodel.git"` | | [`disslucc-continuous`](https://github.com/DisSModel/disslucc-continuous) | Land Use and Cover Change models, continuous allocation (CLUE-inspired) | `pip install "git+https://github.com/DisSModel/disslucc-continuous.git"` | | [`disslucc-discrete`](https://github.com/DisSModel/disslucc-discrete) | Land Use and Cover Change models, discrete allocation (CLUE-inspired) | `pip install "git+https://github.com/DisSModel/disslucc-discrete.git"` | diff --git a/docs/examples.md b/docs/examples.md index a0016c1..4fb7c86 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -125,8 +125,8 @@ Implementations of classic **System Dynamics** models: * **Lorenz Attractor** (Deterministic chaos) * **Coffee Cooling** (Newton's Law of Cooling) -### 🌊 [Coastal-Dynamics](https://github.com/DisSModel/coastal-dynamics) -Advanced research models focused on coastal processes, demonstrating model equivalence between vector and raster substrates for: +### 🌊 [BR-MANGUE](https://github.com/DisSModel/brmangue-dissmodel) +The BR-MANGUE coastal dynamics model, demonstrating model equivalence between vector and raster substrates — validated against the original TerraME implementation — for: * **Mangrove Succession** * **Coastal Flooding** (Flood models) diff --git a/paper.bib b/paper.bib index 8edf02f..b123bde 100644 --- a/paper.bib +++ b/paper.bib @@ -103,12 +103,12 @@ @article{Ferreira2020 doi = {10.3390/rs12244033} } -@software{CoastalDynamics, +@software{BRMangue, author = {Costa, Sérgio Souza and Bezerra, Denilson da Silva}, - title = {coastal-dynamics: Coupled flood and mangrove succession models for DisSModel}, - year = {2025}, + title = {brmangue-dissmodel: The BR-MANGUE coupled flood and mangrove succession model for DisSModel}, + year = {2026}, publisher = {GitHub}, - url = {https://github.com/DisSModel/coastal-dynamics} + url = {https://github.com/DisSModel/brmangue-dissmodel} } @software{DisSModelCA, diff --git a/paper.md b/paper.md index 3409efd..fbf7a49 100644 --- a/paper.md +++ b/paper.md @@ -167,38 +167,47 @@ while throughput scales differently: | Grid | Cells | Raster (ms/step) | Vector (ms/step) | Speedup | |-----:|------:|-----------------:|-----------------:|--------:| -| 10×10 | 100 | 0.15 | 30.11 | 206× | -| 50×50 | 2,500 | 0.20 | 647.22 | 3,164× | -| 100×100 | 10,000 | 0.60 | 2,715.16 | 4,491× | -| 500×500 | 250,000 | 15.36 | — | — | -| 1,000×1,000 | 1,000,000 | 25.85 | — | — | +| 10×10 | 100 | 0.17 | 71.63 | 431× | +| 50×50 | 2,500 | 0.20 | 2,273.33 | 11,278× | +| 100×100 | 10,000 | 0.35 | 6,973.62 | 19,799× | +| 500×500 | 250,000 | 9.67 | — | — | +| 1,000×1,000 | 1,000,000 | 27.32 | — | — | -The raster substrate processes grids of one million cells in approximately 26 ms per +The raster substrate processes grids of one million cells in approximately 27 ms per step. **Domain validation — BR-MANGUE coastal dynamics model.** The conceptual foundation for coupled mangrove-flood modeling in Brazilian coastal zones was established by Bezerra et al. [@Bezerra2013], who discussed the integration of remote sensing and 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. 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: +on this framework, the `brmangue-dissmodel` package [@BRMangue] implements the +BR-MANGUE coupled flood and mangrove succession models on both substrates and +validates them at two levels. + +First, the raster implementation is validated against the original TerraME +implementation over the Maranhão Island dataset (50,496 cells, 20 steps). Outputs +are categorical land-use and soil classes; match percentage is therefore the +appropriate primary metric [@Pontius2008]. At the final step, land use matches on +99.90% of cells and soil on 99.85%; elevation, compared under a strict 1 mm +tolerance, matches on 90.67% of cells with a mean absolute divergence of 0.0033 m. + +Second, cross-substrate equivalence between the vector and raster implementations +is checked over a 60×60 synthetic grid (3,600 cells, EPSG:31984), running 10 +simulation steps: | Band | Match % | MAE | RMSE | Max Error | Cells | |------|--------:|----:|-----:|----------:|------:| | uso (land use) | 100.00% | 0.000000 | 0.000000 | 0.000000 | 3,600 | | solo (soil) | 100.00% | 0.000000 | 0.000000 | 0.000000 | 3,600 | -| alt (elevation)| 99.92% | 0.003086 | 0.008362 | 0.072591 | 3,600 | +| alt (elevation)| 100.00% | 0.000959 | 0.002793 | 0.023864 | 3,600 | -The raster substrate ran at 2.4 ms/step against 70.9 ms/step for the vector -substrate (29.7× speedup). The minor divergence in the elevation band (0.08% of -cells) reflects expected floating-point rounding differences between GeoDataFrame -and NumPy computation paths, not algorithmic disagreement. The `ExperimentRecord` -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. +The raster substrate ran at 5.0 ms/step against 124.4 ms/step for the vector +substrate (24.9× speedup). The residual elevation divergence (max 0.024 m, within +the 0.05 m tolerance) reflects expected floating-point rounding differences between +GeoDataFrame and NumPy computation paths, not algorithmic disagreement. The +`ExperimentRecord` generated by each run captured the full execution provenance — +per-phase timings, input SHA-256 checksum, and artifact paths — automatically, +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], @@ -231,11 +240,11 @@ group (UFMA), supporting studies on mangrove ecosystem dynamics and land-use cha 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 +`DisSLUCC-Continuous`, and `brmangue-dissmodel` — 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 separate distributed execution environment currently under development that -already orchestrates both `DisSLUCC-Continuous` and `coastal-dynamics` in a shared +already orchestrates both `DisSLUCC-Continuous` and `brmangue-dissmodel` 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 From 19f33751573a72aee9bde3c8b1b90010a556adc9 Mon Sep 17 00:00:00 2001 From: Sergio Souza Costa Date: Fri, 12 Jun 2026 09:15:25 -0300 Subject: [PATCH 4/4] doc(paper): trim main text to fit the JOSS 1750-word upper bound JOSS requires papers between 750 and 1750 words; after the BR-MANGUE two-level validation was added the text reached 1795 words. Three surgical cuts bring it to 1745 without losing citations or required content (non-specialist explanation and research applications kept): - drop the redundant 'hybrid data types' sentence in Statement of Need (dual-substrate architecture is already described in the Summary) - compress the TerraME/LUCCME counterpart sentence in Software Design - tighten the ExperimentRecord provenance sentence in Performance Co-Authored-By: Claude Fable 5 --- paper.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/paper.md b/paper.md index fbf7a49..3dc10b5 100644 --- a/paper.md +++ b/paper.md @@ -69,9 +69,7 @@ DisSModel fulfils this need with a lightweight, purpose-built time-stepped scheduler coupled directly to vector and raster spatial state, providing a Pythonic implementation of the TerraME paradigm, democratising access to complex modeling for territorial planners and -environmental scientists. It offers native support for hybrid data -types — Geo-fields and Geo-objects — allowing for simulations that remain -interoperable with modern machine learning and GIS workflows. +environmental scientists. Beyond simulation execution, reproducibility is a first-class concern in DisSModel. The `executor` module provides a standardised lifecycle — `validate → load → run → save` @@ -149,11 +147,9 @@ 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. +the same `ModelExecutor` contract — an explicit Python counterpart to the original +TerraME/LUCCME stack. All three packages serve as reference implementations for +researchers building their own domain extensions. ## Performance @@ -204,10 +200,9 @@ simulation steps: The raster substrate ran at 5.0 ms/step against 124.4 ms/step for the vector substrate (24.9× speedup). The residual elevation divergence (max 0.024 m, within the 0.05 m tolerance) reflects expected floating-point rounding differences between -GeoDataFrame and NumPy computation paths, not algorithmic disagreement. The -`ExperimentRecord` generated by each run captured the full execution provenance — -per-phase timings, input SHA-256 checksum, and artifact paths — automatically, -with zero additional instrumentation by the modeller. +GeoDataFrame and NumPy computation paths, not algorithmic disagreement. Each run +automatically produced an `ExperimentRecord` with per-phase timings, input SHA-256 +checksum, and artifact paths — no additional instrumentation by the modeller. **Domain validation — DisSLUCC-Continuous LUCC model.** The `DisSLUCC-Continuous` package implements the continuous CLUE-like allocation algorithm [@Veldkamp1996],