DisSModel — Discrete Spatial Modeling Ecosystem

Open Source · MIT License · Actively developed

A Python ecosystem for spatially explicit dynamic modeling — Cellular Automata, System Dynamics, and Land Use & Cover Change simulation.

An independent, unofficial Python alternative to TerraME — with equivalent packages for Cellular Automata (dissmodel-ca) and System Dynamics (dissmodel-sysdyn), and Agent-Based Modeling (dissmodel-abm) on the way.

📖 Documentation 📚 Book (in progress) 💻 GitHub Organization

$ pip install dissmodel Copied!

Release notes in the changelog.

If DisSModel is useful in your work, you can cite it: doi:10.5281/zenodo.23246106

Ecosystem map

How the pieces fit together, so far

DisSModel is an independent Python alternative that takes TerraME as its conceptual basis. The dissmodel core is the most mature piece, and the packages marked in green have been checked against TerraME and LuccME outputs. This map shows where things stand today.

This map shows the packages. The full ecosystem also includes the reference outputs, benchmarks, study cases, workflow and book hosted by LambdaGeo.

🗺 See how every repository connects

Design

Designed with modularity and reproducibility in mind

Every simulation is a traceable experiment, with coefficients kept in versioned TOML files rather than buried in code.

Experiment as a first-class object

Each run produces an ExperimentRecord capturing provenance, input SHA-256 checksums, parameters, and the code version, so results can be cited in a paper.

Configuration separated from code

Calibrated coefficients live in versioned TOML files in dissmodel-configs and are reviewed via PR before publication. This keeps them out of the code and citeable by git hash.

Two-layer architecture

Science logic stays in the Model layer, while the ModelExecutor handles I/O, column mapping, and provenance, so that the science code stays as untouched as possible.

Infrastructure for experimentation

A platform prototype built on JupyterLab, FastAPI, Redis, and MinIO via Docker Compose, not yet production-ready. On the data side, disscube can already read Brazil Data Cube collections through their STAC catalog.

┌─────────────────────────────────┐
│  DisSModel Platform (prototype) │
│                                 │
│  FastAPI                        │
│   ├── POST /submit_job          │
│   ├── GET  /job/{id}            │
│   └── POST /experiments/repro   │
│                                 │
│  Worker                         │
│   ├── ExecutorRegistry          │
│   ├── ModelExecutor ABC         │
│   └── Dask Client               │
├─────────────────────────────────┤
│  dissmodel-configs              │
│   ├── models/brmangue.toml      │
│   └── models/disslucc.toml      │
├─────────────────────────────────┤
│  Infrastructure                 │
│  JupyterLab · MinIO · Dask      │
└─────────────────────────────────┘

Case Study

Coastal dynamics & Mangrove migration

The brmangue-dissmodel repository is our first case study, applying DisSModel to data from Maranhão, Brazil: flood propagation and mangrove migration based on Bezerra et al. (2013). So far it has been compared with a TerraME 2.0 adaptation of the original model in two scenarios, with land use and soil matching in the baseline one. More scenarios are on the way.

Model

Simulation logic kept separate from I/O and infrastructure, so it can be used in a notebook or script.

from dissmodel.core import Environment
from brmangue.models.vector.flood_model import FloodModel
from brmangue.models.vector.mangrove_model import MangroveModel

env = Environment(start_time=1, end_time=88)

FloodModel(gdf=gdf, sea_level_rise_rate=0.5)
MangroveModel(gdf=gdf, sea_level_rise_rate=0.5, tide_height=6.0)

env.run()

↓

ModelExecutor

Wraps the model with I/O, column mapping, provenance, and platform integration.

class BrmangueVectorExecutor(ModelExecutor):
    name = "brmangue_vector"

    def load(self, record: ExperimentRecord) -> GeoDataFrame:
        # load + apply column_map → canonical names
        ...

    def run(self, data, record: ExperimentRecord):
        # build env + models, call env.run()
        ...

↓

Run

The same executor can run locally via CLI or through the platform API (the API is experimental).

python examples/main_vector.py run \
  --input  examples/data/input/synthetic_grid_60x60_shp.zip \
  --output examples/data/output/simulation.gpkg \
  --param  end_time=88 \
  --param  sea_level_rise_rate=0.5

curl -X POST http://localhost:8000/submit_job \
  -d '{
    "model_name":    "brmangue_vector",
    "input_dataset": "s3://inputs/grid.shp",
    "parameters":    {"end_time": 88}
  }'

Documentation for the three libraries