r3.univar.openmp - GRASS manual

NAME

r3.univar.openmp - Calculates per-zone univariate statistics for every Z-slice of a RASTER3D volume (one slice = one time step).
Single-process, OpenMP-parallel-over-Z-slices alternative to running t.rast.univar[.openmp] against a space time raster dataset with hundreds of registered maps: convert the STRDS to a RASTER3D volume once with t.rast.to.rast3, then read it here -- each thread opens the volume ONCE instead of once per map, eliminating the dominant per-map file-open overhead on long time series. Output columns (zone, start, mean, ...) match t.rast.univar.openmp's CSV format closely enough to be a drop-in forcing source for r.hydro.hbv.forcing.

KEYWORDS

raster3d, statistics, time, parallel

SYNOPSIS

r3.univar.openmp

r3.univar.openmp --help

r3.univar.openmp [-u] input=name [zones=name] start=string [increment=integer] [nprocs=integer] [output=name] [separator=character] format=name [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-u: Suppress printing of column names
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

input=name [required]: Name of input 3D raster map
zones=name: Raster map used for zoning, must be of type CELL
start=string [required]: Date (YYYY-MM-DD) of Z-index 0 -- RASTER3D volumes carry no per-slice timestamp of their own, so this and increment= reconstruct one, matching the STRDS's own chronological order that t.rast.to.rast3 preserved when building the volume
increment=integer: Days between consecutive Z-slices; Default: 1
nprocs=integer: Number of threads for parallel computing; Number of OpenMP threads (parallelized across Z-slices); Default: 0
output=name: Name for output file
separator=character: Field separator; Special characters: pipe, comma, space, tab, newline
format=name [required]: Output format; Options: plain, csv; Default: csv; plain: Plain text output; csv: CSV (Comma Separated Values)

DESCRIPTION
EXAMPLE
SEE ALSO
AUTHORS

DESCRIPTION

r3.univar.openmp calculates per-zone univariate statistics for every Z-slice (time step) of a RASTER3D volume, in a single process, parallelizing across Z-slices with OpenMP.

It exists to fix a real performance problem in t.rast.univar.openmp (and t.rast.univar) that only shows up on long time series: both process a space time raster dataset's registered maps one at a time, and for each map, every OpenMP thread (or, for t.rast.univar, every worker process) opens its own file descriptor to that one map. For a 730-map daily STRDS at nprocs=32, that is 23,360 total file-open calls -- confirmed in practice to dominate runtime (6-14 minutes per variable) even after restricting the region to a small basin, since the per-map open/close cost does not shrink with region size.

The fix: convert the STRDS to a single RASTER3D volume first, with t.rast.to.rast3 (one Z-slice per registered map, in chronological order). r3.univar.openmp then opens that volume exactly nprocs times -- once per thread, for the whole run -- and each thread reads a contiguous range of Z-slices through its own file descriptor, row by row (not a whole slice at once, to keep memory bounded for large regions). This collapses the file-open count from (n_maps × nprocs) to just nprocs.

RASTER3D volumes carry no per-slice timestamp of their own (Z is a plain spatial index), so start (the date of Z-index 0) and increment (days between slices, default 1) reconstruct one, assuming t.rast.to.rast3 preserved the input STRDS's chronological order -- true by construction for a daily STRDS with no gaps, which is the expected use case here.

If a zones raster map is provided (must share the RASTER3D volume's own rows/cols), statistics are computed per zone per Z-slice, in a format close enough to t.rast.univar.openmp's own CSV output (columns start, zone, mean, plus count/min/max/stddev/sum) to be usable as-is as forcing input to r.hydro.hbv.forcing -- confirmed in practice against the same numbers t.rast.univar.openmp produces for the same STRDS, converted first.

EXAMPLE

t.rast.to.rast3 input=hbv_era5_precipitation output=hbv_era5_precipitation_r3
r3.univar.openmp input=hbv_era5_precipitation_r3 zones=basin19_subbasins \
  start=2021-01-01 nprocs=32 output=basin19_precip_table.csv

AUTHORS

Yann Chemin

SOURCE CODE

Available at: r3.univar.openmp source code (history)

Accessed: Sunday Sep 13 08:27:31 2026