Ribasim Water Resources Development
This skill provides essential context for AI coding assistants working on the Ribasim water resources modeling system.
Project Overview
Ribasim is a multi-language water resources modeling system with:
**Julia core**: Simulation engine using differential equations and optimization**Python API**: Model building utilities and programmatic interface**QGIS plugin**: Visual model editing and visualization**Domain**: Hydrology, water resources, scientific computingRepository Structure
Understand the modular architecture:
```
core/ # Julia simulation engine (OrdinaryDiffEq.jl, JuMP.jl)
python/ # Python packages (ribasim, ribasim_api, testmodels)
ribasim_qgis/ # QGIS plugin for visualization
docs/ # Quarto documentation
build/ # CLI build scripts
generated_testmodels/ # Auto-generated test cases
models/ # Working directory (gitignored)
utils/ # Utility scripts
```
Development Workflow
Environment Setup
Use Pixi as the primary package manager:
```bash
pixi run install # Install all dependencies
pixi run test-ribasim-python # Run Python tests
pixi run test-ribasim-core # Run Julia tests
pixi run quarto-preview # Preview documentation
pixi run generate-testmodels # Generate test models
```
Key Configuration Files
`pixi.toml`: Development tasks and environment`Project.toml`: Julia development dependencies`core/Project.toml`: Julia package dependencies`python/ribasim/pyproject.toml`: Python package configTechnology Stack
Julia Core Dependencies
**OrdinaryDiffEq.jl**: Differential equation solver (primary)**JuMP.jl**: Mathematical optimization modeling**HiGHS.jl**: Linear/mixed-integer programming**Arrow.jl**: Columnar data I/O**SQLite.jl**: Database operations**MetaGraphsNext.jl**: Network topology graphs**SciML ecosystem**: Scientific ML toolsPython Stack
**Pandas/GeoPandas**: Data manipulation and geospatial**PyArrow**: Arrow integration with Julia**Pydantic/Pandera**: Data validation**Matplotlib**: VisualizationCode Patterns & Conventions
Julia Style
Follow community conventions and multiple dispatch patternsPrefer immutable structs; use `@kwdef` for defaultsCheck type stability with `@code_warntype`Avoid allocations in simulation loopsProfile with `@profile` and `@benchmark`Use PrecompileTools.jl to reduce startup timeAim for static compilation compatibilityPython Style
Follow PEP 8 and use ruff for lintingUse type hints extensivelyDefine data structures with Pydantic modelsPrefer pandas method chainingInclude runnable examples in docstrings (used by quartodoc)File Naming
Julia: `snake_case.jl`Python: `snake_case.py`Tests: `test_*.py` (Python), `*_test.jl` (Julia)Data Flow & Integration
Primary Formats
**SQLite/GeoPackage**: Model database storage**Arrow**: Large tables and results exchange**TOML**: Configuration files**NetCDF**: Interoperability exportCross-Language Integration
Julia ↔ Python: SQLite database + Arrow filesQGIS reads/writes same formats as PythonSubprocess calls from Python to Julia CLIConsistent table schemas across languagesKey Data Structures
Network graph (node-link water system representation)TimeSeries (time-dependent boundary conditions)Spatial geometries (basin polygons, link linestrings)Control logic (pump/gate rules)Common Development Tasks
Adding New Node Types
1. Define Julia struct in `core/src/`
2. Create Python Pydantic model in `python/ribasim/`
3. Update schema validation
4. Add network topology handling
5. Update documentation and tests
Modifying Solvers
Core logic in `core/src/solve.jl`Integration tests in `core/integration_test/`Add regression tests for numerical stabilityAdding Python Features
Follow patterns in `python/ribasim/`Write comprehensive docstrings with examplesAdd tests in `python/*/tests/`Mark regression tests with `@pytest.mark.regression`Testing Strategy
Julia Tests
Unit tests: `core/test/`Integration tests: `core/integration_test/`Regression tests: `core/regression_test/`Python Tests
Unit tests: `python/*/tests/`Use `@pytest.mark.regression` for regression testsDebugging & Performance
Julia Debugging
Use `@show` for quick inspectionJulia debugger for step-throughProfile hot paths to avoid allocationsCheck type stability to prevent performance issuesPython Debugging
Standard tools: `breakpoint()` for PDBPydantic provides rich validation errorsUse vectorized pandas operations for performanceCommon Gotchas
1. **Julia compilation**: First run is slow; expect JIT warmup
2. **Table schemas**: Maintain compatibility between Julia/Python schemas
3. **Coordinate systems**: Be explicit about CRS in geospatial ops
4. **Numerical precision**: Water balance calculations need careful handling
5. **Arrow exchange**: Ensure consistent column types across languages
Documentation Standards
User docs in `docs/` (Quarto, published to ribasim.org)API docs auto-generated from docstringsComments should explain *why*, not *what*Include runnable examples in docstringsKey Entry Points
`core/src/Ribasim.jl`: Main Julia module`python/ribasim/ribasim/model.py`: Core Python model classGitHub repository: `Deltares/Ribasim` (issues and PRs)Documentation: https://ribasim.org/Best Practices
Check existing similar components for established patternsReview tests to understand expected usageUse Pixi tasks for consistencyFollow domain-specific conventions for water modelingMaintain compatibility across Julia/Python/QGIS interfacesWrite comprehensive tests for numerical stability