Ribasim Water Resources Modeling Development Assistant
You are assisting with development on **Ribasim**, a water resources modeling system. This is a multi-language scientific computing project with domain-specific requirements in hydrology and water resource management.
Project Context
Ribasim is a modular water resources simulation system with:
**Core Engine**: Julia-based differential equation solver**Model Building**: Python API and utilities**Visualization**: QGIS plugin integration**Domain**: Hydrology, water balance, network flow modelingRepository 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
```
Key Technologies
Julia Stack (Core Engine)
**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 toolsPython Stack (Utilities & API)
**Pandas/GeoPandas**: Data manipulation and geospatial processing**PyArrow**: Arrow format integration with Julia**Pydantic/Pandera**: Data modeling and validation**Matplotlib**: Visualization and plottingDevelopment Tools
**Pixi**: Primary package/environment manager and task runner**Pytest**: Python testing framework**Quarto**: Documentation generation**Pre-commit**: Code quality hooksDevelopment Workflow
Environment Setup
```bash
pixi run install # Install and configure all dependencies
```
Common Commands
```bash
Testing
pixi run test-ribasim-python # Python tests
pixi run test-ribasim-core # Julia tests
Documentation
pixi run quarto-preview # Preview docs locally
Model Generation
pixi run generate-testmodels # Generate test models
```
Check `pixi.toml` for all available tasks.
Code Guidelines
Julia Code Style
Follow Julia community conventions (see Julia style guide)Use multiple dispatch extensivelyPrefer immutable structs where possibleUse `@kwdef` for struct definitions with defaultsFile naming: `snake_case.jl`Test files: `*_test.jl`Avoid allocations during simulation loopsCheck for type instabilities using `@code_warntype`Aim for static compilation compatibilityPython Code Style
Follow PEP 8Use ruff for formatting/lintingType hints requiredUse Pydantic models for data structuresPandas-style method chaining where appropriateFile naming: `snake_case.py`Test files: `test_*.py`Comprehensive docstrings (used by quartodoc for API docs)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 interoperabilityKey Data Structures
**Network Graph**: Node-link representation of water system (MetaGraphsNext.jl)**TimeSeries**: Time-dependent boundary conditions**Spatial Geometries**: Basin area polygons, link linestrings**Control Logic**: Rules for pumps, gates, and other hydraulic structuresJulia ↔ Python Integration
SQLite database and Arrow files for model storageArrow format for efficient data exchangeSubprocess calls from Python to Julia CLIShared table schemas (ensure compatibility)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 tests
Modifying Solvers
Core solver logic: `core/src/solve.jl`Integration tests: `core/integration_test/`Regression tests for numerical stabilityProfile performance with `@profile` and `@benchmark`Adding Python Features
Follow patterns in `python/ribasim/`Add comprehensive docstrings with examplesInclude 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/`Use `@show` for quick debuggingJulia debugger for step-through debuggingPython Tests
Unit tests: `python/*/tests/`Use `pytest.mark.regression` for regression testsUse `breakpoint()` for debuggingPydantic provides rich validation error messagesPerformance Considerations
Julia Core
Avoid allocations during simulationAim for static compilation compatibilityProfile with `@profile` and `@benchmark`Use PrecompileTools.jl to reduce startup timeAvoid type instabilitiesPython Components
Use vectorized pandas operationsLeverage GeoPandas for spatial operationsKey Files
`core/src/Ribasim.jl`: Main Julia module entry point`python/ribasim/ribasim/model.py`: Core Python model class`pixi.toml`: Development environment and task definitions`Project.toml`: Julia development dependencies`core/Project.toml`: Julia package dependencies`python/ribasim/pyproject.toml`: Python package configurationDocumentation
**User docs**: `docs/` directory (Quarto-based, published to ribasim.org)**API docs**: Auto-generated from docstrings**Code comments**: Focus on *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 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
5. **QGIS plugin**: Must read/write same formats as Python components
Resources
**Documentation**: https://ribasim.org/**Repository**: https://github.com/Deltares/Ribasim**Issues/PRs**: GitHub repository**Developer docs**: `docs/dev/` directoryInstructions for AI Assistant
When working on Ribasim:
1. **Identify the component**: Determine if the task involves Julia core, Python utilities, or QGIS integration
2. **Follow language conventions**: Use appropriate style guides for Julia or Python
3. **Consider data flow**: Understand how data moves between components (SQLite, Arrow)
4. **Check existing patterns**: Look at similar components for established patterns
5. **Write tests**: Add comprehensive tests following the project's testing strategy
6. **Update documentation**: Include docstrings and update relevant documentation
7. **Performance matters**: For Julia core, pay attention to allocations and type stability
8. **Domain awareness**: Remember this is scientific computing for water resources—numerical precision and physical validity matter
9. **Use Pixi tasks**: Run tests and checks via `pixi run <task>` commands
Always consult existing code for patterns, refer to tests for expected usage, and prioritize numerical correctness and performance in the core simulation engine.