Ribasim Water Resources Modeling Assistant
Expert assistant for developing and maintaining the Ribasim water resources modeling system.
Project Context
**Ribasim** is a multi-language water resources modeling system with a Julia simulation engine, Python utilities/API, and QGIS integration for visualization.
**Primary Language**: Julia (core simulation engine)**Secondary Languages**: Python (model building, API), QGIS plugin**Domain**: Water resources modeling, hydrology, scientific computing**Repository**: https://github.com/Deltares/RibasimRepository Structure
```
core/ # Julia core engine (main simulation code)
python/ # Python components (ribasim, ribasim_api, ribasim_testmodels)
ribasim_qgis/ # QGIS plugin for model visualization
docs/ # Quarto-based documentation
build/ # Build scripts for CLI
generated_testmodels/ # Generated test models
models/ # Working directory (git-ignored)
utils/ # Utility scripts
```
Key Technologies
Julia Stack
**OrdinaryDiffEq.jl**: Differential equation solving**JuMP.jl**: Mathematical optimization**HiGHS.jl**: Linear/mixed-integer programming solver**Arrow.jl**: Columnar data I/O**SQLite.jl**: Database operations**MetaGraphsNext.jl**: Network topology graphs**SciML ecosystem**: Scientific machine learningPython Stack
**Pandas/GeoPandas**: Data manipulation and geospatial processing**PyArrow**: Arrow format integration**Pydantic/Pandera**: Data modeling and validation**Matplotlib**: VisualizationBuild & Development
**Pixi**: Primary package/environment manager (see `pixi.toml`)**Julia Package Manager**: Dependency management (`Project.toml`, `core/Project.toml`)**Pre-commit**: Code quality hooks**Pytest**: Python testing**Quarto**: Documentation generationInstructions
1. Environment Setup
Always use Pixi for environment management:
```bash
pixi run install # Install and configure all dependencies
```
2. Development Commands
**Testing:**
```bash
pixi run test-ribasim-python # Python tests
pixi run test-ribasim-core # Julia tests
```
**Documentation:**
```bash
pixi run quarto-preview # Preview docs locally
```
**Model Generation:**
```bash
pixi run generate-testmodels # Generate test models
```
3. Code Architecture Patterns
**Julia Core (`core/src/`):**
Built around OrdinaryDiffEq.jl patterns with callbacksNetwork topology using MetaGraphsNext.jlUse multiple dispatch extensivelyPrefer immutable structs with `@kwdef` for defaultsFollow Julia community conventions**Python Components:**
Pydantic models for data validation and serializationPandas-style method chaining for data processingGeoPandas for spatial operationsArrow format for seamless data exchange with JuliaFollow PEP 8 and use ruff for lintingUse type hints extensively4. File Naming Conventions
Julia: `snake_case.jl`Python: `snake_case.py`Tests: `test_*.py` (Python), `*_test.jl` (Julia)5. Data Flow & Formats
**Primary Data Formats:**
**SQLite/GeoPackage**: Model database storage**Arrow**: Large results or tables**TOML**: Configuration files**NetCDF**: Conversion for interoperability**Key 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)6. Adding New Node Types
When adding new node types, follow this workflow:
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
7. Modifying Solvers
Core solver logic: `core/src/solve.jl`Integration tests: `core/integration_test/`Regression tests for numerical stability8. Adding Python Features
Follow patterns in `python/ribasim/`Add comprehensive docstrings (used by quartodoc)Include runnable examples in docstringsAdd tests in `python/*/tests/`9. Testing Strategy
**Julia Tests:**
Unit tests: `core/test/`Integration tests: `core/integration_test/`Regression tests: `core/regression_test/`**Python Tests:**
Unit tests: `python/*/tests/`Mark regression tests with `@pytest.mark.regression`10. Performance Considerations
**Julia Core:**
Avoid allocations during simulationAim towards static compilabilityProfile with `@profile` and `@benchmark`Use PrecompileTools.jl to reduce startup timeAvoid type instabilities (check with `@code_warntype`)**Python Components:**
Use vectorized pandas operations11. Debugging
**Julia:**
Use `@show` for quick variable inspectionJulia debugger for step-through debugging**Python:**
Use `breakpoint()` for PDBRich error messages from Pydantic validation12. Integration Points
**Julia ↔ Python:**
SQLite database and Arrow files for model storageArrow format for data exchangeSubprocess calls from Python to Julia CLI**QGIS Plugin:**
Reads/writes same formats as Python componentsGUI for model visualizationGenerates compatible model files13. Documentation
**User docs**: `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 docstrings14. Common Gotchas
1. **Julia compilation**: First run is slow due to compilation
2. **Table schema**: Ensure compatibility between Julia and Python
3. **Coordinate systems**: Be explicit about CRS in geospatial operations
4. **Numerical precision**: Water balance calculations require careful handling
15. Key Files to Understand
`core/src/Ribasim.jl`: Main Julia module entry point (core/src/Ribasim.jl:1)`python/ribasim/ribasim/model.py`: Core Python model class (python/ribasim/ribasim/model.py:1)`pixi.toml`: Development environment and task definitions (pixi.toml:1)`Project.toml`: Julia development dependencies (Project.toml:1)`core/Project.toml`: Julia package dependencies (core/Project.toml:1)`python/ribasim/pyproject.toml`: Python package configuration (python/ribasim/pyproject.toml:1)Resources
**Documentation**: https://ribasim.org/**Issues**: GitHub issues at https://github.com/Deltares/Ribasim**Developer docs**: See `docs/dev` directory**Code patterns**: Review existing similar components**Tests**: Existing tests demonstrate expected usage patternsConstraints
Always use GitHub repository https://github.com/Deltares/Ribasim for issues and PRsMaintain compatibility between Julia and Python table schemasPrioritize numerical stability in water balance calculationsEnsure geospatial operations specify coordinate reference systems explicitly