Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions paper.bib
Original file line number Diff line number Diff line change
Expand Up @@ -126,3 +126,34 @@ @software{DisSModelSysDyn
publisher = {GitHub},
url = {https://github.com/DisSModel/dissmodel-sysdyn}
}

@article{Pontius2008,
author = {Pontius, Robert Gilmore and Peethambaram, Sneha and Castella, Jean-Christophe},
title = {Comparison of Three Maps at Multiple Resolutions: a Case Study of Land Change Simulation in Cho Don District, Vietnam},
journal = {Annals of the Association of American Geographers},
year = {2008},
volume = {98},
number = {1},
pages = {28--49}
}


@article{Willmott2005,
author = {Willmott, Cort J. and Matsuura, Kenji},
title = {Advantages of the mean absolute error ({MAE}) over the root mean
square error ({RMSE}) in assessing average model performance},
journal = {Climate Research},
year = {2005},
volume = {30},
pages = {79--82}
}


@article{Veldkamp1996,
author = {Veldkamp, A. and Fresco, L. O.},
title = {{CLUE}: a conceptual model to study the conversion of land use and its effects},
journal = {Ecological Modelling},
year = {1996},
volume = {85},
pages = {253--270}
}
66 changes: 52 additions & 14 deletions paper.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,8 @@ Beyond simulation execution, reproducibility is a first-class concern in DisSMod
The `executor` module provides a standardised lifecycle — `validate → load → run → save`
— that captures provenance metadata (input checksums, parameters, timing, output
paths) in an `ExperimentRecord` object automatically generated for every run. This
design ensures that results produced locally or via CLI are fully traceable without additional instrumentation by the modeller.
design ensures that results produced locally or via CLI are fully traceable without
additional instrumentation by the modeller.

## State of the Field

Expand Down Expand Up @@ -138,13 +139,19 @@ explicit `fmt` argument. For cloud deployments, the same API resolves
interactive dashboards, and `RasterMap` for step-by-step raster rendering in both
headless and interactive modes.

The extensibility of DisSModel's class hierarchy has already produced two domain
packages distributed independently on PyPI: `dissmodel-ca` [@DisSModelCA], which
provides ready-to-use Cellular Automata patterns built on `RasterCellularAutomaton`,
and `dissmodel-sysdyn` [@DisSModelSysDyn], which adds System Dynamics compartmental
models as first-class DisSModel components. Both packages follow the same
`ModelExecutor` contract and serve as reference implementations for researchers
building their own domain extensions.
The extensibility of DisSModel's class hierarchy has already produced domain
packages distributed independently on PyPI. `dissmodel-ca` [@DisSModelCA] provides
ready-to-use Cellular Automata patterns built on `RasterCellularAutomaton`.
`dissmodel-sysdyn` [@DisSModelSysDyn] adds System Dynamics compartmental models as
first-class DisSModel components. `DisSLUCC-Continuous` [@DisSLUCCContinuous]
implements the continuous LUCC modeling components of the LUCCME framework — Demand,
Potential, and Allocation — following the three-pillar architecture proposed by
@Veldkamp1996 and @Verburg2004, on both vector and raster substrates and following
the same `ModelExecutor` contract. This last package establishes an explicit Python
counterpart to the original TerraME/LUCCME stack, where DisSModel occupies the role
of TerraME and DisSLUCC-Continuous occupies the role of LUCCME. All three packages
serve as reference implementations for researchers building their own domain
extensions.

## Performance

Expand Down Expand Up @@ -173,8 +180,9 @@ Bezerra et al. [@Bezerra2013], who discussed the integration of remote sensing a
computational models to assess sea-level rise impacts on mangrove ecosystems. Building
on this framework, the `coastal-dynamics` package [@CoastalDynamics] implements
coupled flood and mangrove succession models over the same spatial domain on both
substrates. Running 20 simulation steps over a 60×60 synthetic grid (3,600 cells,
EPSG:31984) produces the following results:
substrates. Outputs are categorical land-use and soil classes; match percentage is
therefore the appropriate primary metric [@Pontius2008]. Running 20 simulation steps
over a 60×60 synthetic grid (3,600 cells, EPSG:31984) produces the following results:

| Band | Match % | MAE | RMSE | Max Error | Cells |
|------|--------:|----:|-----:|----------:|------:|
Expand All @@ -190,6 +198,27 @@ generated by this run captured the full execution provenance automatically:
load phase 2.898 s (49.4%), run phase 2.972 s (50.6%), input SHA-256 checksum,
and artifact paths — with zero additional instrumentation by the modeller.

**Domain validation — DisSLUCC-Continuous LUCC model.** The `DisSLUCC-Continuous`
package implements the continuous CLUE-like allocation algorithm [@Veldkamp1996],
in which each cell holds a fractional land-use proportion rather than a discrete
class. For continuous outputs, fixed-threshold match statistics are not meaningful for
real-valued spatial data [@Pontius2008]; MAE is the appropriate primary metric,
as it provides a directly interpretable measure of average model error [@Willmott2005]. Running 6 simulation steps over the Lab1 study area (6,574 cells)
and comparing against a TerraME/LUCCME reference result produces the following:

| Comparison | MAE | RMSE | Max Error | Cells |
|---|----:|-----:|----------:|------:|
| Vector vs TerraME | 0.003583 | 0.006188 | 0.027355 | 6,574 |
| Raster vs TerraME | 0.003583 | 0.006188 | 0.027355 | 6,574 |
| Vector vs Raster | 0.000000 | 0.000000 | 0.000000 | 6,574 |

Both substrates reproduce the TerraME/LUCCME reference with a MAE of 0.0036 in
[0,1] scale — consistent with expected floating-point divergence between independent
Lua and Python implementations of the same continuous allocation algorithm. Vector
and raster substrates are numerically identical (MAE = 0.000), confirming that the
3.6× performance gain of the raster substrate (39.9 ms/step vs 143.2 ms/step)
introduces no algorithmic divergence.

## Research Impact Statement

DisSModel provides a critical bridge for the environmental modeling community. By
Expand All @@ -199,11 +228,20 @@ framework has already been instrumental in academic research at the **LambdaGeo*
group (UFMA), supporting studies on mangrove ecosystem dynamics and land-use change,
building upon established spatial modeling practices [@Verburg2004; @SantosJunior2025].

The emergence of independent domain packages — `dissmodel-ca`, `dissmodel-sysdyn`,
`DisSLUCC-Continuous`, and `coastal-dynamics` — without modifications to the core
framework demonstrates that the `ModelExecutor` contract is stable and sufficient for
real-world modeling requirements. This is further evidenced by the DisSModel
Platform, a distributed execution environment currently under development that
already orchestrates both `DisSLUCC-Continuous` and `coastal-dynamics` in a shared
test infrastructure, running each through the same job queue without any change to
their scientific code. The platform validates the central design principle of
DisSModel: that simulation science should not need to be rewritten to run in
production.

This architecture positions DisSModel as the simulation layer in the Brazilian Earth
Observation stack — complementary to SITS [@Simoes2021] for present-state land
classification and the Brazil Data Cube [@Ferreira2020] for satellite data
access — and is designed to scale toward Pangeo-style ensemble runs via Dask
delayed operations over shared loaded datasets.
classification and the Brazil Data Cube [@Ferreira2020] for satellite data access.

## AI Usage Disclosure

Expand All @@ -212,4 +250,4 @@ Jules) to assist with structuring documentation, synthesising prior work, and
generating submission checklists. All outputs were reviewed and validated by the
human authors.

## References
## References
Loading