Standard workflow: VRain → VBasin → hydrodynamic model

This document describes the end-to-end hydrological analysis workflow that the VRain suite and VBasin are built around, and the file contracts that connect the three stages.

 ┌─────────────────────────┐    vrain_design_rainfall.json    ┌──────────────────────────────┐    batas_hidrodinamik/    ┌────────────────────────┐
 │ 1. VRain                │ ───────────────────────────────▶ │ 2. VBasin                    │ ────────────────────────▶ │ 3. Hydrodynamic model  │
 │ rainfall data, design   │   depth per return period,       │ DEM → sub-basins → HEC-HMS   │  hydrographs per         │ HEC-RAS 1D/2D, VFlood, │
 │ rainfall, storm pattern │   Huff pattern, per sub-basin    │ flood / low-flow discharge   │  computation point       │ MIKE, iRIC, ...        │
 └─────────────────────────┘                                  └──────────────────────────────┘                           └────────────────────────┘

Each arrow is a file, not a copy-and-paste step: the numbers that appear in the VRain report are the numbers the HEC-HMS model is driven with, and the hydrographs HEC-HMS produces are what the hydraulic model receives.

Stage 1 — VRain: design rainfall and storm events

VRain is a suite of seven desktop tools (Windows, no installation). Pick the entry point by the data you have:

Every VRain tool writes the hand-off file vrain_design_rainfall.json next to its usual outputs (VRainMaster: output folder, plus one file per pathway VRain_VBasin_<Pathway>.json; VRainBasin: 07_VBasin/; VRainFreq: next to the Excel export; VRainStorm: pattern-only ..._vbasin_pattern_...json). The format is documented in VRAIN_PACKAGE_SPEC.md.

What to check before moving on

• The package scope: basin/subbasin depths are areal and ready to use; point depths are gauge values and need an areal reduction factor or a basin target in VBasin.
• The return periods you need (2, 5, 10, 25, 50, 100 …) are all present — VBasin does not interpolate between return periods.
• For sub-daily pathways the depth is quoted at the dominant storm duration, not at 24 h; VBasin uses it as the storm total for that duration.

Stage 2 — VBasin: terrain preprocessing and discharge modelling

VBasin (VBasin.exe, python gui.py, or the vbasin CLI) is organised in five tabs that follow the modelling order.

Tab 1 · DAS (shared stage)

1. DEM — load DEMNAS/other GeoTIFF, or fetch HydroSHEDS / Copernicus for a bounding box or an Indonesian Wilayah Sungai name.
2. Reference channels — OSM (Overpass) or your own vector file; optional clip to the WS boundary.
3. Points — outlet / upstream end by map click or CSV.
4. DEM reconditioning — AGREE stream burning (smooth_drop, sharp_drop, buffer_cells), bed-profile reconstruction, optional official-basin ridge.
5. Validation — correctness / completeness / F1 of the derived network, basin-boundary agreement, calibration sweep.
6. Network delineation — control points → Subbasins / Junctions / Reaches (HEC-HMS Basin Model), morphometry, lag (SCS/Kirpich), Curve Number (uniform, file, OSM landuse, Esri Sentinel-2 LULC + HYSOGs). Exports GPKG, SHP, network.basin, publication map, QGIS project, network_state.pkl.

Tab 2A · BANJIR (flood, event simulation)

1b. Design rainfall — source Paket VRain (default): choose the JSON, click Muat Paket VRain. VBasin reads the depths for the checked return periods (DAS-wide, or per Sub-DAS when names match), and loads the Huff pattern into the manual hyetograph table when the box is ticked. Other sources remain available: own grid (frequency fit inside VBasin) and the hujan-id station platform. Bangun Hujan Rancangan builds one hyetograph per Sub-DAS per return period (Mononobe alternating-block, or the imported pattern). With the VRain source every Sub-DAS receives the VRain basin depth, or its own depth when the package carries sub-basins; the hujan-id station catalogue is not consulted, so no outside dataset is blended into the VRain numbers and the hujan-id files need not be installed. 2. Build HEC-HMS project — .hms, .basin, .met, .gage, .dss, .control, .run: one Meteorologic Model and one Simulation Run per return period. Open in HEC-HMS → Compute (or let the YAML pipeline run HEC-HMS headless). 3. Results — read Run_*.dss, produce hydrograph plots, peak tables, peak map, HTML report, PowerPoint, and — with the checkbox on — the hydrodynamic boundary-condition package (Stage 3).

Tab 2B · DEBIT ANDALAN (low flow, continuous simulation)

Historical rainfall (CSV / GPM folder / NetCDF) → continuous HEC-HMS model (Deficit-Constant or SMA, monthly ET, recession baseflow) → optional water-balance calibration → flow-duration curve, Q80/Q90/Q95, monthly flows, AWLR QC and calibration report.

Tab 3 · STRUKTUR

River-corridor screening at a structure point: thalweg, cross-sections, Manning capacity, stage–storage, inundation levels, geomorphology, survey plan.

Tab 4 · PROYEK

One YAML control file records every input and setting (vbasin project --template kontrol.yaml writes a commented template). The flood section accepts the VRain package directly:

banjir:
  return_periods: [2, 5, 10, 25, 50, 100]
  rainfall_source: vrain
  vrain_package_path: "../VRain/output/vrain_design_rainfall.json"
  vrain_scope: auto          # per Sub-DAS when names match, else DAS-wide
  vrain_use_pattern: true    # Huff pattern from the package
  storm_duration_hr: 6.0     # used only when the package carries no pattern
  dt_hr: 1.0

vbasin project --control kontrol.yaml (or Jalankan Model in the GUI) then builds the rainfall, writes and runs the HEC-HMS project, produces the reports and the boundary-condition package, and saves a copy of the control file that was actually used.

Project folder layout

<project root>/
  01_DAS/                         network GPKG/SHP, network.basin, maps, network_state.pkl
  02_BANJIR/
    01_hujan_rancangan/           hyetographs per Sub-DAS per RP, summary CSV
    02_model_hms/<proj>_Banjir/   complete HEC-HMS project, Run_*.dss, reports
    03_batas_hidrodinamik/        RP2/, RP25/, ... boundary packages (Stage 3)
  03_DEBIT_ANDALAN/
    01_kalibrasi_awlr/
    02_model_hms/
  04_LAPORAN_TERPADU/             integrated Word report
  <proj>_kontrol_dipakai.yaml     audit copy of the settings used

Stage 3 — hydrodynamic model

The boundary-condition package (vstream.hydro_export) is written per HEC-HMS Run — by the YAML pipeline into 02_BANJIR/03_batas_hidrodinamik/RP<T>/, by the GUI result panel into <output>/batas_hidrodinamik/, or by vbasin export-bc --dss Run_X.dss --run "Run Banjir 25th" --network network_state.pkl --outdir bc.

batas_hidrodinamik/RP25/
  README.md                 how to use in HEC-RAS and VFlood, table of points
  boundary_points.csv/.gpkg each Computation Point: x, y, lon, lat, cumulative
                            area, peak Q, time to peak, volume, file names
  hydrographs/<Point>.csv   datetime, jam_ke, Q_m3s
  hecras_paste/<Point>.txt  one value per line for the Flow Hydrograph table
  dss_pathnames.csv         DSS pathnames to read the series directly from the HMS DSS
  vflood_inflows.yaml       rivers.inflows block for VFlood (vflood-turbo)
peaks_by_rp.csv             Computation Point × return period peak table

HEC-RAS — Unsteady Flow Data → Flow Hydrograph at the upstream boundary → Read from DSS (pathname from dss_pathnames.csv) or Enter Table (interval and start time are stated in the README; paste hecras_paste/<Point>.txt). For 2D models, place boundary-condition lines at the x,y of the points (boundary_points.gpkg opens in RAS Mapper / QGIS).

VFlood — merge vflood_inflows.yaml into the project's vflood.yaml; each inflow references its CSV with time_column: datetime, column: Q_m3s.

Which discharge? A Computation Point carries the cumulative discharge of everything upstream. If the hydraulic model also receives lateral runoff along a reach, export with elements=all and use the Sub-DAS series instead, so the inflow is not counted twice.

Reproducibility checklist

• VRain report and vrain_design_rainfall.json come from the same run (the JSON records the generator, pathway, distribution and report path).
• VBasin YAML control file points at that JSON; the *_kontrol_dipakai.yaml copy in the output root matches what you intended.
• network_state.pkl used for the flood run is the delineation you validated (F1, basin agreement) in Tab 1.
• Return periods in VRain ⊇ return periods in VBasin.
• Boundary package README.md states the interval and start time your hydraulic model expects.

Environments and versions