2. Quick start

If you already have an RRI project folder (RRI_Input.txt + topo/, rain/, etc. — either an original RRI project or a new one, the format is identical):

vflood-rri path/to/RRI_Input.txt

This prints a summary of the loaded grid, then runs the full simulation and writes output files to wherever RRI_Input.txt says to put them (./out/hs_, ./out/hr_, etc. — same convention as the original RRI: prefix + zero-padded step + .out).

Useful flags:

vflood-rri RRI_Input.txt --hours 3     # quick test run: only simulate the first 3 hours
vflood-rri RRI_Input.txt --quiet       # suppress per-step progress printing

Note on --hours: it also rescales the output cadence so you still get one snapshot per hour (rather than the file's original outnum, which assumes the full run length). Don't use --hours for a real run you intend to keep — it's a smoke-test convenience only.

Example

vflood-rri "D:\...\rokan15s_\RRI_Input.txt"

vflood-rri: D:\...\RRI_Input.txt  (388x446 grid, 5597 river cells, 87582 active cells, 264h @ dt=600s)
  step    1  t=      3600s  hs_max=0.0001  hr_max=0.0003  qr_max=0.0001
  step    2  t=      7200s  hs_max=0.0002  hr_max=0.0016  qr_max=0.0020
  ...
VFlood-RRI: done in 187.4s

Real calendar dates alongside every step, when known: RRI_Input.txt's own clock is always relative — the original Fortran format has no field for a real-world date, and adding one would break exact-format compatibility. Instead, scaffold_project/ scaffold_project_with_spinup write a lightweight companion file, start_date.txt (best- effort, from a rain_geotiff_stack's first band name), whenever the rainfall source's real start date is knowable. vflood-rri (and VFloodControl) read it automatically:

  step    1  t=      3600s  [2023-09-17 01:00]  hs_max=0.0001  hr_max=0.0003  qr_max=0.0001

The same file is picked up by vflood-netcdf (real CF time units), vflood-export --formats kml (--start becomes optional), and vflood-analyze hydrograph/combined's chart x-axes (real dates instead of hours). No start_date.txt (a hand-built project, or one scaffolded before this existed) just falls back to relative time everywhere.

Resuming a run

RRI_Input.txt's own init_slo/riv/gw/gampt_ff_switch + initfile_slo/riv/gw/ gampt_ff fields (unchanged from upstream RRI) let a run start from saved state instead of always cold-starting at zero — set the switch to 1 and point the matching initfile_* at a grid. The exact same .out format every simulation already writes works unmodified as an init file (RRI.f90's own reader just clamps <= 0 values — including a .out file's own -0.1 "outside domain" sentinel — down to 0), so the natural way to resume is to point initfile_hs/ initfile_hr/etc. straight at a previous run's own hs_NNNNNN.out/hr_NNNNNN.out.

The one thing this does not do automatically: shift your rainfall/boundary data to match. Just like upstream RRI, VFlood-RRI's own internal clock always restarts at t=0 on every run, init file or not — rain.dat/boundary files are read from their own time origin regardless of what hour the loaded state represents. Feeding a "resumed" run the original, full-storm rain.dat replays the storm's very beginning onto the already-flooded state, which diverges fast and hard (confirmed directly: doing this by mistake produced ~1m of spurious hr error within 3 hours). The correct workflow is to also prepare a rain.dat whose own t=0 corresponds to your resume point — e.g. to resume from hour 48, subtract 48*3600 from every timestamp in the original rain.dat, drop any record that goes negative, and point the resumed run's config at that trimmed file instead. Verified this way (proper state + a correctly time-shifted rain.dat), a 3-hour resumed run matches an equivalent continuous run to within millimeters — not a coincidence, an actual reproducibility check.