High-level runner (runlib)

geoswe.runlib is the coastal surge and rain runner behind the paper’s county-to-continental applications. It loads a prepared case (bed, Manning, active mask, ring boundary), wires the forcings, and drives the dense or compressed solver. It is a library, not a command: no module in it has a __main__ guard, and the scripts under benchmark/pinellas_3m/ (run_pinellas_mpi.py) show how a case runner calls it. It assumes a coastal case near sea level (the bed is clipped to -10..50 m, a coastal ring and sponge are applied, Green-Ampt infiltration is on in fp32 unless GEOSWE_GA=0), so for other problems build the solvers directly, as in the flood tutorial.

import geoswe.runlib works on a NumPy-only install. case, cli and replay import their optional dependencies inside the functions that need them; driver, which needs CuPy, mpi4py and pandas at import, is the one submodule the package does not import for you, so ask for it explicitly with from geoswe.runlib import driver.

Case loading

geoswe.runlib.case.load_case(case_path, bc_path, *, dtype='float32', nhd_path=None, channel_bed_npz=None, burn_target_m=-0.5, burn_max_drop_m=2.0, burn_elev_cutoff_m=5.0, proc_dtype='float64', say=None)

Load + condition the global case grid + ring-BC arrays. Pure NumPy (no GPU/MPI).

proc_dtype is the precision of the conditioning itself (clip, smooth, burn). Use “float64”, the default, to reproduce the published Pinellas runs bit for bit. “float32” is the lean production path: differences of under a centimetre and no float64 transient, which is what matters at CONUS scale (about 58 GB against 116 GB for the global bed).

Options of the case runners

geoswe.runlib.cli.build_parser(extra=None)

Build the shared argument parser for the coastal surge+rain runners.

extra is an optional callable that receives the parser and adds runner-specific options before it is returned.

geoswe.runlib.cli.parse(argv=None, extra=None)

Parse argv (default sys.argv) with build_parser().

Driver and cache replay

geoswe.runlib.driver.main(args, *, comm, gauge_csv_map, tide_dir, t0_ts, proc_dtype='float64', sponge_impl='elementwise')

Run a coastal surge+rain case end-to-end.

Parameter contract:

• comm: a real mpi4py communicator (comm.rank is used unconditionally); pass MPI.COMM_WORLD even single-rank.

• gauge_csv_map: {station_name: csv_filename} for the ring gauges.

• tide_dir: pathlib.Path containing those CSVs.

• t0_ts: tz-aware pandas.Timestamp of simulation t=0.

• proc_dtype: dtype for host-side preprocessing arrays.

• sponge_impl: "elementwise", the full-grid sponge kernel of the published 3 m runs, or "band", the band-only kernel of the 10 m runs. They differ only in the dead open-ocean corner, which the band kernel damps twice.

A failure on one rank aborts the whole job, instead of leaving the other ranks waiting in the next collective until the scheduler’s wall clock.

build_cached_parser is where the replay entry point’s own options are defined, the checkpoint and wall-clock ones among them (--checkpoint-every-h, --ckpt-dir, --resume, --max-wall-min, --stop-at-epoch, --stop-buffer-min).

geoswe.runlib.replay.main(args, *, comm)

Run (or resume) a compressed-cache replay. comm is the mpi4py communicator (or None).

The caller pins one GPU per rank (cp.cuda.Device(rank % ngpu).use()) before any CuPy-heavy import, which is why this module imports nothing heavy at module level. This function then resolves the wall-clock deadline, opens the rank-0 run.log (appended, so a resumed leg continues the same file), writes the run manifest beside it, and hands the cache to geoswe.compressed_solver.run_cached().

geoswe.runlib.replay.build_cached_parser()

Argument parser for the cache-replay entry point (run a saved flat cache without rebuilding the mesh).