Work in progress · Open Source · MIT License
DisSModel — Discrete Spatial Modeling Ecosystem

A Python ecosystem, still under development, for spatially explicit dynamic modeling — we are exploring Cellular Automata, System Dynamics, and Land Use & Cover Change simulation.

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

📖 Documentation 📚 Book (in progress) 💻 GitHub Organization
$ pip install dissmodel Copied!

Early-stage releases — APIs may change between versions.

Ecosystem

Repositories

Each package aims to have a focused role. The core can be used on its own, and the extensions can be combined as the ecosystem matures. Some packages are more mature than others.

Project status: DisSModel is under active development. APIs, documentation, and results may change, and there are rough edges we are still smoothing out. Feedback, bug reports, and contributions are very welcome — come say hello on GitHub.
Loading repositories from GitHub…

Design

Designed with modularity and reproducibility in mind

We aim to make every simulation a traceable experiment, keeping coefficients in versioned TOML files rather than buried in code. These are design goals we are working toward, and they are still evolving.

Experiment as a first-class object

Each run is meant to produce an ExperimentRecord capturing provenance, input SHA-256 checksums, and the model commit, to support citing results in a paper.

Configuration separated from code

Calibrated coefficients live in versioned TOML files in dissmodel-configs and are reviewed via PR before publication. The goal is to keep 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 prototype platform built on JupyterLab, FastAPI, Redis, and MinIO via Docker Compose. It is not yet hardened for production use; Pangeo / BDC integration is planned for a future release.

┌─────────────────────────────────┐
│  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/dissluc.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. It is an ongoing implementation of flood propagation and mangrove migration based on Bezerra et al. (2014), and we are still validating and refining it.

Model

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

from dissmodel import Environment

env = Environment(start_time=2008, end_time=2030)

FloodModel(gdf=gdf, taxa_elevacao=0.5, attr_uso="uso")
MangroveModel(gdf=gdf, altura_mare=6.0, attr_solo="solo")

env.run()
↓
ModelExecutor

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

class CoastalVectorExecutor(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 still experimental).

python main.py run \
  --input  data/input/mangue_grid.zip \
  --output data/output/simulation.gpkg \
  --param  end_time=2030