diff --git a/README.md b/README.md index c7a2e35..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 | --- @@ -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. --- @@ -223,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"` | @@ -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/) 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 a20e929..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` @@ -94,7 +92,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 +124,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 +133,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 @@ -150,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 @@ -168,38 +163,46 @@ 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. 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], @@ -232,11 +235,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 distributed execution environment currently under development that -already orchestrates both `DisSLUCC-Continuous` and `coastal-dynamics` in a shared +Platform, a separate distributed execution environment currently under development that +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