r.univar: Add parallel support (OSGeo#1634)

Co-authored-by: Anna Petrasova <kratochanna@gmail.com>

raster/r.univar/Makefile

@@ -1,9 +1,10 @@
 
 MODULE_TOPDIR = ../..
 
-LIBES2 = $(RASTERLIB) $(GISLIB) $(MATHLIB)
-LIBES3 = $(RASTER3DLIB) $(RASTERLIB) $(GISLIB) $(MATHLIB)
+LIBES2 = $(RASTERLIB) $(GISLIB) $(MATHLIB) $(OMPLIB)
+LIBES3 = $(RASTER3DLIB) $(RASTERLIB) $(GISLIB) $(MATHLIB) $(OMPLIB)
 DEPENDENCIES = $(RASTER3DDEP) $(GISDEP) $(RASTERDEP)
+EXTRA_CFLAGS = $(OMPCFLAGS)
 
 PROGRAMS = r.univar r3.univar
 

raster/r.univar/benchmark/benchmark_r_univar.py

@@ -0,0 +1,54 @@
+"""Benchmarking of r.univar
+
+@author Aaron Saw Min Sern
+"""
+
+from grass.exceptions import CalledModuleError
+from grass.pygrass.modules import Module
+from subprocess import DEVNULL
+
+import grass.benchmark as bm
+
+
+def main():
+    results = []
+
+    # Users can add more or modify existing reference maps
+    benchmark(7071, "r.univar_50M", results)
+    benchmark(10000, "r.univar_100M", results)
+    benchmark(14142, "r.univar_200M", results)
+    benchmark(20000, "r.univar_400M", results)
+
+    bm.nprocs_plot(results)
+
+
+def benchmark(size, label, results):
+    reference = "r_univar_reference_map"
+    output = "benchmark_r_univar_nprocs"
+
+    generate_map(rows=size, cols=size, fname=reference)
+    module = Module(
+        "r.univar",
+        map=reference,
+        run_=False,
+        stdout_=DEVNULL,
+        overwrite=True,
+    )
+    results.append(bm.benchmark_nprocs(module, label=label, max_nprocs=16, repeat=3))
+    Module("g.remove", quiet=True, flags="f", type="raster", name=reference)
+    Module("g.remove", quiet=True, flags="f", type="raster", name=output)
+
+
+def generate_map(rows, cols, fname):
+    Module("g.region", flags="p", s=0, n=rows, w=0, e=cols, res=1)
+    # Generate using r.random.surface if r.surf.fractal fails
+    try:
+        print("Generating reference map using r.surf.fractal...")
+        Module("r.surf.fractal", output=fname)
+    except CalledModuleError:
+        print("r.surf.fractal fails, using r.random.surface instead...")
+        Module("r.random.surface", output=fname)
+
+
+if __name__ == "__main__":
+    main()

raster/r.univar/globals.h

@@ -56,7 +56,7 @@ typedef struct
 typedef struct
 {
     struct Option *inputfile, *zonefile, *percentile, *output_file,
-        *separator;
+        *separator, *nprocs;
     struct Flag *shell_style, *extended, *table, *use_rast_region;
 } param_type;
 

raster/r.univar/r.univar.html

@@ -48,6 +48,28 @@ <h2>NOTES</h2>
 map and uploads statistics to new attribute columns, see
 <em><a href="v.rast.stats.html">v.rast.stats</a></em>.
 
+<h3>PERFORMANCE</h3>
+
+<p>
+<em>r.univar</em> suports parallel processing using OpenMP. The user
+can specify the number of threads to be used with the <b>nprocs</b> parameter.
+However, parallelization is disabled when the <b>-e</b> extended statistics
+flag is used.
+
+<p>
+Due to the differences in summation order, users may encounter small floating points
+discrepancies when <em>r.univar</em> is run on very large raster files when different
+<b>nprocs</b> parameters are used. However, since the work allocation among threads
+is static, users should expect to have the same results when run with the same 
+number of threads.
+
+<div align="center" style="margin: 10px">
+    <img src="r_univar_benchmark_size.png" alt="benchmark for number of cells" border="0">
+    <br>
+    <i>Figure: Benchmark shows execution time for different
+    number of cells and cores. See benchmark scripts in source code. </i>
+    </div>
+
 <h2>EXAMPLES</h2>
 
 <h3>Univariate statistics</h3>