Ribasim Water Resources Development

This skill provides comprehensive guidance for AI coding assistants working on the Ribasim water resources modeling system.

Project Overview

Ribasim is a multi-language water resources modeling system with components in Julia (core simulation engine), Python (utilities/API), and QGIS integration. The project uses GitHub at https://github.com/Deltares/Ribasim for issues and PRs.

**Key Characteristics:**

Primary Language: Julia (core simulation engine)

Secondary Languages: Python (model building, QGIS plugin)

Domain: Water resources modeling, hydrology, scientific computing

Architecture: Modular system with CLI, Python API, and QGIS plugin

Documentation: https://ribasim.org/

Repository Structure

```

├── core/ # Julia core engine (main simulation code)

│ ├── src/ # Core Julia source code

│ ├── test/ # Julia unit tests

│ └── Project.toml # Julia package configuration

├── python/ # Python components

│ ├── ribasim/ # Main Python package (model building)

│ ├── ribasim_api/ # Python API for model interaction

│ └── ribasim_testmodels/ # Test model generation

├── ribasim_qgis/ # QGIS plugin for model visualization

├── docs/ # Documentation (Quarto-based)

├── build/ # Build scripts for CLI

├── generated_testmodels/ # Generated test models

├── models/ # Working directory for models, ignored by git

└── utils/ # Utility scripts

```

Development Workflow

Environment Setup

Use Pixi as the primary package/environment manager:

```bash

pixi run install # Install and configure all dependencies

```

Key Development Commands

**Testing:**

```bash

pixi run test-ribasim-python # Run Python tests

pixi run test-ribasim-core # Run Julia tests

```

**Documentation:**

```bash

pixi run quarto-preview # Preview docs locally

```

**Model Generation:**

```bash

pixi run generate-testmodels # Generate test models

```

All tasks are defined in `pixi.toml`.

Key Technologies & Dependencies

Julia Stack (Core)

**OrdinaryDiffEq.jl**: Differential equation solving (primary solver)

**JuMP.jl**: Mathematical optimization modeling

**HiGHS.jl**: Linear/mixed-integer programming solver

**Arrow.jl**: Columnar data format for I/O

**SQLite.jl**: Database operations

**MetaGraphsNext.jl**: Graph data structures for network topology

**SciML ecosystem**: Scientific machine learning tools

Python Stack

**Pandas/GeoPandas**: Data manipulation and geospatial processing

**PyArrow**: Arrow format integration with Julia

**Pydantic/Pandera**: Data modeling and validation

**Matplotlib**: Visualization and plotting

Build & Development

**Pixi**: Primary package/environment manager

**Julia Package Manager**: For Julia dependencies

**Pre-commit**: Code quality hooks

**Pytest**: Python testing

**Quarto**: Documentation generation

Code Style & Conventions

Julia Code Style

Follow Julia community conventions

Use multiple dispatch extensively

Prefer immutable structs where possible

Use `@kwdef` for struct definitions with defaults

File naming: `snake_case.jl`

Tests: `*_test.jl`

Python Code Style

Follow PEP 8

Use ruff for linting

Use type hints extensively

Pydantic models for data structures

Pandas-style method chaining where appropriate

File naming: `snake_case.py`

Tests: `test_*.py`

Architecture Patterns

Julia Core (`core/src/`)

Built around OrdinaryDiffEq.jl patterns with callbacks

Network topology using MetaGraphsNext.jl

Core solver logic in `core/src/solve.jl`

Entry point: `core/src/Ribasim.jl`

Python Components

Pydantic (pandera) models for data validation and serialization

Pandas workflows for data processing pipelines

GeoPandas for spatial operations

Arrow format for seamless data exchange with Julia core

Core model class: `python/ribasim/ribasim/model.py`

Data Flow & Formats

Primary Data Formats

**SQLite/GeoPackage**: Model database storage

**Arrow**: Results or tables too large for SQLite

**TOML**: Configuration files

**NetCDF**: Conversion format for interoperability

Key Data Structures

**Network Graph**: Node-link representation of water system

**TimeSeries**: Time-dependent boundary conditions

**Spatial Geometries**: Basin area polygons, link linestrings

**Control Logic**: Rules for pumps, gates, etc.

Integration Points

**Julia ↔ Python:**

SQLite database and Arrow files for model storage

Arrow format for data exchange

Subprocess calls from Python to Julia CLI

**QGIS Plugin:**

Reads/writes same formats as Python components

Provides GUI for model visualization

Generates compatible model files

Common Development Tasks

Adding New Node Types

When adding a new node type to the water system:

1. Define Julia struct in `core/src/`

2. Add Python Pydantic model in `python/ribasim/`

3. Update schema validation

4. Add to network topology handling

5. Update documentation and tests

Modifying Solvers

When working on solver logic:

Core solver logic: `core/src/solve.jl`

Integration tests: `core/integration_test/`

Regression tests: Test for numerical stability

Adding Python Features

When adding new Python functionality:

1. Follow patterns in `python/ribasim/`

2. Add comprehensive docstrings (used by quartodoc)

3. Include runnable examples in docstrings

4. Add tests in `python/ribasim/tests/`

Testing Strategy

Julia Tests

**Unit tests**: `core/test/`

**Integration tests**: `core/integration_test/`

**Regression tests**: `core/regression_test/`

Python Tests

**Unit tests**: `python/*/tests/`

**Regression tests**: Mark with `@pytest.mark.regression`

Performance Considerations

Julia Core

Avoid allocations during simulation

Aim towards making it statically compilable

Profile with `@profile` and `@benchmark`

Use PrecompileTools.jl for reducing startup time

Avoid type instabilities (check with `@code_warntype`)

Python Components

Use vectorized pandas operations for efficiency

Leverage GeoPandas spatial indexing

Debugging

Julia

Use `@show` for quick variable inspection

Julia debugger for step-through debugging

Check type stability with `@code_warntype`

Python

Standard Python debugging tools

Use `breakpoint()` for PDB

Rich error messages from Pydantic validation

Documentation Guidelines

**User docs**: Located in `docs/` (Quarto-based, published to ribasim.org)

**API docs**: Auto-generated from docstrings

**Code comments**: Focus on *why*, not *what*

**Examples**: Include runnable examples in docstrings

Common Gotchas

1. **Julia compilation**: First run is slow due to compilation overhead

2. **Table schema**: Ensure compatibility between Julia and Python table schemas

3. **Coordinate systems**: Be explicit about CRS in geospatial operations

4. **Numerical precision**: Water balance calculations require careful numerical handling

Key Configuration Files

`pixi.toml`: Development environment and task definitions

`Project.toml`: Julia development dependencies

`core/Project.toml`: Julia package dependencies

`python/ribasim/pyproject.toml`: Python package configuration

Getting Help

Documentation: https://ribasim.org/

Issues: GitHub issues for bugs and feature requests

Code patterns: Review existing similar components for established patterns

Tests: Existing tests demonstrate expected usage patterns

Ribasim Water Resources Development

Ribasim Water Resources Development

Project Overview

Repository Structure

Development Workflow

Environment Setup

Key Development Commands

Key Technologies & Dependencies

Julia Stack (Core)

Python Stack

Build & Development

Code Style & Conventions

Julia Code Style

Python Code Style

Architecture Patterns

Julia Core (`core/src/`)

Python Components

Data Flow & Formats

Primary Data Formats

Key Data Structures

Integration Points

Common Development Tasks

Adding New Node Types

Modifying Solvers

Adding Python Features

Testing Strategy

Julia Tests

Python Tests

Performance Considerations

Julia Core

Python Components

Debugging

Julia

Python

Documentation Guidelines

Common Gotchas

Key Configuration Files

Getting Help

Reviews (0)