Ribasim Water Resources Modeling
You are an expert development assistant for the **Ribasim** project - a water resources modeling system used for hydrological simulation and water management.
Project Context
Ribasim is a multi-language scientific computing project focused on water resources modeling:
**Core Engine**: Julia-based simulation engine using OrdinaryDiffEq.jl and JuMP.jl**Python Components**: Model building API, utilities, and test model generation**QGIS Integration**: Plugin for model visualization and editing**Domain**: Hydrology, water resources, scientific computing, network modeling**Repository**: https://github.com/Deltares/RibasimRepository Structure
```
core/ # Julia simulation engine
├── src/ # Core Julia source
├── test/ # Julia unit tests
└── Project.toml # Package dependencies
python/ # Python components
├── ribasim/ # Model building package
├── ribasim_api/ # Python API
└── ribasim_testmodels/ # Test generation
ribasim_qgis/ # QGIS plugin
docs/ # Quarto documentation
build/ # CLI build scripts
pixi.toml # Environment & tasks
```
Technology Stack
Julia Core
**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 graph topology**SciML ecosystem**: Scientific ML toolsPython Stack
**Pandas/GeoPandas**: Data manipulation and geospatial**PyArrow**: Arrow format integration**Pydantic/Pandera**: Data validation**Matplotlib**: VisualizationDevelopment Tools
**Pixi**: Primary package/environment manager (see `pixi.toml` for tasks)**Pre-commit**: Code quality hooks**Pytest**: Python testing**Quarto**: Documentation generationDevelopment Workflow
Setup
```bash
pixi run install # Install all dependencies
```
Common Tasks
```bash
pixi run test-ribasim-core # Run Julia tests
pixi run test-ribasim-python # Run Python tests
pixi run generate-testmodels # Generate test models
pixi run quarto-preview # Preview documentation
```
Key Files
`pixi.toml` - Environment config and task definitions`core/src/Ribasim.jl` - Main Julia module entry point`python/ribasim/ribasim/model.py` - Core Python model class`Project.toml` - Julia development dependencies`core/Project.toml` - Julia package dependencies`python/ribasim/pyproject.toml` - Python package configCode Architecture & Patterns
Julia Core (`core/src/`)
**Solver pattern**: Built around OrdinaryDiffEq.jl with callbacks**Multiple dispatch**: Use extensively for type-specific behavior**Immutable structs**: Prefer where possible, use `@kwdef` for defaults**Network topology**: MetaGraphsNext.jl for graph representation**Performance**: Avoid allocations in simulation loops, aim for static compilation compatibilityPython Components
**Pydantic models**: Data validation and serialization (with pandera)**Pandas workflows**: Method chaining for data pipelines**GeoPandas**: Heavy spatial operations usage**Type hints**: Use extensively throughout**Style**: Follow PEP 8, use ruff formatterFile Naming
Julia: `snake_case.jl`Python: `snake_case.py`Tests: `test_*.py` (Python), `*_test.jl` (Julia)Data Flow & Formats
Primary Formats
**SQLite/GeoPackage**: Model database storage**Arrow**: Large results/tables**TOML**: Configuration files**NetCDF**: Interoperability exportsKey Data Structures
Network graph (node-link water system representation)Time series (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. Add Python Pydantic model in `python/ribasim/`
3. Update schema validation
4. Add to network topology handling
5. Update documentation and add 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/*/tests/`Testing Strategy
Julia
Unit: `core/test/`Integration: `core/integration_test/`Regression: `core/regression_test/`Python
Unit: `python/*/tests/`Mark regressions: `@pytest.mark.regression`Performance Guidelines
Julia
Avoid allocations during simulationProfile with `@profile` and `@benchmark`Check type stability with `@code_warntype`Use PrecompileTools.jl to reduce startup timeAim for static compilation compatibilityPython
Use vectorized pandas operationsProfile memory-intensive operationsDebugging
Julia
`@show` for quick inspectionJulia debugger for step-throughPython
`breakpoint()` for PDBRich Pydantic validation errorsIntegration Points
Julia ↔ Python
SQLite database and Arrow files for model storageArrow format for efficient data exchangeSubprocess calls from Python to Julia CLIQGIS Plugin
Reads/writes same formats as PythonGUI for model visualizationGenerates compatible model filesDocumentation
**User docs**: `docs/` (Quarto-based, published to ribasim.org)**API docs**: Auto-generated from docstrings**Comments**: Focus on *why*, not *what***Examples**: Include runnable examples in docstrings**Reference**: See `docs/dev` for detailed developer documentationCommon Gotchas
1. **Julia compilation**: First run slow due to JIT compilation
2. **Table schema**: Ensure Julia/Python schema compatibility
3. **Coordinate systems**: Always be explicit about CRS in geospatial ops
4. **Numerical precision**: Water balance requires careful handling
5. **Type stability**: Watch for performance cliffs from type instabilities
Code Style
Julia
Follow Julia community conventionsUse multiple dispatch extensivelyPrefer immutable structsUse `@kwdef` for structs with defaultsPython
Follow PEP 8Use ruff for formattingType hints requiredPydantic for data structuresResources
**Documentation**: https://ribasim.org/**Issues/PRs**: https://github.com/Deltares/Ribasim**Code patterns**: Study existing similar components**Test examples**: Tests show expected usage patternsInstructions for AI Assistant
When working on Ribasim:
1. **Understand the domain**: This is scientific water resources modeling - precision and correctness are critical
2. **Check existing patterns**: Look at similar components before implementing new features
3. **Maintain compatibility**: Ensure Julia/Python data exchange remains compatible
4. **Test thoroughly**: Add unit tests for new features, regression tests for numerical changes
5. **Document clearly**: Include docstrings with examples, update relevant docs
6. **Performance matters**: Profile Julia code for type stability and allocations
7. **Use Pixi tasks**: Run tests and tasks via `pixi run <task>` commands
8. **Follow conventions**: Respect established code style and architectural patterns
9. **Ask when uncertain**: Water modeling has domain-specific requirements - better to clarify than guess