Ribasim Water Resources Development
Expert assistant for developing the Ribasim water resources modeling system - a multi-language project with Julia core engine, Python utilities, and QGIS integration.
Project Context
Ribasim is a water resources modeling system with:
**Julia core** (`core/`) - Main simulation engine using OrdinaryDiffEq.jl**Python utilities** (`python/`) - Model building, API, test models**QGIS plugin** (`ribasim_qgis/`) - Model visualization**Documentation** (`docs/`) - Quarto-based user/dev docs**GitHub repo**: https://github.com/Deltares/RibasimTechnology Stack
Julia (Core Engine)
OrdinaryDiffEq.jl - Differential equation solvingJuMP.jl - Mathematical optimizationHiGHS.jl - Linear/mixed-integer programmingArrow.jl, SQLite.jl - Data I/OMetaGraphsNext.jl - Network topology graphsSciML ecosystem - Scientific ML toolsPython (Utilities)
Pandas/GeoPandas - Data manipulation and geospatialPyArrow - Arrow format integrationPydantic/Pandera - Data validationMatplotlib - VisualizationPytest - TestingDevelopment Tools
**Pixi** - Primary package/environment manager (see `pixi.toml`)Julia Package Manager - `Project.toml` (dev deps) and `core/Project.toml` (core deps)Pre-commit - Code quality hooksQuarto - Documentation generationDevelopment Workflow
Setup
```bash
pixi run install # Install and configure all dependencies
```
Testing
```bash
pixi run test-ribasim-python # Python tests
pixi run test-ribasim-core # Julia tests
pixi run generate-testmodels # Generate test models
```
Documentation
```bash
pixi run quarto-preview # Preview docs locally
```
Code Patterns & Conventions
Julia Code Style
Follow Julia community conventionsUse multiple dispatch extensivelyPrefer immutable structs where possibleUse `@kwdef` for struct definitions with defaultsAvoid type instabilities - check with `@code_warntype`Avoid allocations during simulation for performanceProfile with `@profile` and `@benchmark`Use PrecompileTools.jl to reduce startup timeAim towards static compilabilityPython Code Style
Follow PEP 8, use ruff for lintingUse type hints extensivelyPydantic models for data structuresPandas-style method chaining where appropriateVectorized pandas operations for performanceFile Naming
Julia: `snake_case.jl`Python: `snake_case.py`Tests: `test_*.py` (Python), `*_test.jl` (Julia)Data Formats & Flow
Primary Formats
**SQLite/GeoPackage** - Model database storage**Arrow** - Results or large tables**TOML** - Configuration files**NetCDF** - Export format for interoperabilityKey Data Structures
Network graph (node-link water system representation)TimeSeries (time-dependent boundary conditions)Spatial geometries (basin polygons, link linestrings)Control logic (rules for pumps, gates)Integration
**Julia ↔ Python**: SQLite database + Arrow files for data exchange**QGIS Plugin**: Reads/writes same formats, provides GUI for visualizationCommon Development Tasks
Adding New Node Types
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
Core logic: `core/src/solve.jl`Integration tests: `core/integration_test/`Regression tests for numerical stabilityAdding Python Features
Follow patterns in `python/ribasim/`Add comprehensive docstrings (used by quartodoc)Include runnable examples in docstringsAdd tests in `python/ribasim/tests/`Testing Strategy
Julia
Unit tests: `core/test/`Integration tests: `core/integration_test/`Regression tests: `core/regression_test/`Debugger: Use Julia debugger for step-throughQuick inspection: `@show` macroPython
Unit tests: `python/*/tests/`Mark regression tests: `@pytest.mark.regression`Debugging: Use `breakpoint()` for PDBKey Files Reference
`core/src/Ribasim.jl` - Main Julia module entry point`python/ribasim/ribasim/model.py` - Core Python model class`pixi.toml` - Development environment and tasks`Project.toml` - Julia dev dependencies`core/Project.toml` - Julia package dependencies`python/ribasim/pyproject.toml` - Python package configDocumentation Guidelines
**User docs**: `docs/` directory (Quarto, published to ribasim.org)**API docs**: Auto-generated from docstrings**Code comments**: Explain *why*, not *what***Examples**: Include runnable examples in docstringsCommon Gotchas
1. **Julia compilation** - First run is slow due to JIT compilation
2. **Table schema** - Ensure Julia/Python schema compatibility
3. **Coordinate systems** - Be explicit about CRS in geospatial ops
4. **Numerical precision** - Water balance calculations need careful handling
5. **Type stability** - Julia performance depends on type-stable code
Getting Help
Documentation: https://ribasim.org/Issues/PRs: https://github.com/Deltares/RibasimCode patterns: Study existing similar componentsTests: Show expected usage patternsConstraints
Water balance calculations require careful numerical handlingSolver modifications should include regression testsAll new node types need both Julia and Python implementationsMaintain compatibility between SQLite schema and Arrow formatQGIS plugin must remain compatible with Python components