Add irrigation proof-of-concept

[HendrikKok]

Fixes #3118

Irrigation module; proof-of-concept

Adds a standalone irrigation/ module wrapping Wflow's SBM land-surface
components (soil, interception, runoff, non-paddy demand) to prototype a
coupled irrigation loop with Ribasim.

Structure

irrigation/
├── Project.toml               # Julia environment (pinned Wflow source)
├── Manifest.toml              # Exact dependency versions
├── README.md
├── src/
│   ├── irrigation.jl          # Irrigation module (wraps Wflow components)
│   └── irrigation_utils.jl    # Config structs, forcing, logger
└── example/
    ├── coupled_simulation.jl  # Coupled Ribasim + irrigation run
    ├── run_irrigation_standalone.jl  # Standalone run with plots
    ├── run_irrigation_coupled.py     # Python driver: generate model + run
    └── plot_results.py        # Result visualisation

Coupling concept

Each timestep has the following update pattern:

sequenceDiagram
    participant W as Irrigation module
    participant A as Allocation (LP)
    participant P as Physical layer (ODE)

    loop every allocation timestep
        Note over W: get_demand!() — soil state @ t-1
        W->>A: demand [m/s] → user_demand.demand

        Note over A: update_allocation!()<br/>LP solve for t
        A->>P: allocated flows [m³/s]

        Note over P: SciMLBase.step!()<br/>ODE water balance solve for t

        P->>W: realized volumes [m³] 
        Note over W: update!() — advance soil to t
    end

Loading

Online coupling API

# initialise
Irrigation.init()

# Ribasim.solve!(model)
    for each allocation timestep
        Irrigation.get_demand!()        # [m/s] — soil state @ t-1
        → LP solve → ODE step            # advance Ribasim to t
        Irrigation.set_allocated!(realized)
        Irrigation.update!()            # advance soil to t
    end

# finalize to flush logger
Irrigation.finalize!()

Notes

• Wflow pinned to ea8754e (1.1.0-dev) via [sources] in irrigation/Project.toml; remove when 1.1.0 is released to the registry
• run_irrigation_standalone.jl runs three standalone scenarios (no allocation / 50% / multi-column) and saves water budget plots
• run_irrigation_coupled.py generates the Ribasim model and runs coupled_simulation.jl, saving the same water budget plots

IO design

• Time-dependent meteo input (precipitation, potential ET) is read from the GeoPackage via the UserDemand irrigation_forcing table
• Soil/vegetation parameters are initialised from built-in defaults (SoilConfig, VegetationConfig, IrrigationConfig); could be overridden from HydroMT NetCDF output in the future
• The irrigation_id → UserDemand node mapping is implicit: each UserDemand node with irrigation = true gets one soil column; irr.node_id (held by Ribasim) is the ordered index into the soil column vector — no separate config needed

Open questions

• Could we reuse Wflow's existing NetCDF parsing to read HydroMT spatial parameter grids directly, rather than writing a custom reader? Concern: Wflow's reader is built around 2D spatial grids

[github-advanced-security]

Trivy found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.