Updated README 📚

* Expanded description of OpenMP section.
serkor1 · Jan 3, 2025 · 72d550a · 72d550a
1 parent 9c636ba
commit 72d550a
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 11 deletions.
diff --git a/README.Rmd b/README.Rmd
@@ -270,20 +270,38 @@ summary(
 ```
 
 ## :information_source: OpenMP support
+```{r OpenMP setup, echo = FALSE}
+# Set column names for both
+# examples
+column_names <- c("Iterations", "Runtime (sec)" ,"Garbage Collections [gc()]", "gc() pr. second", "Memory Allocation (MB)")
+```
 
 > [!IMPORTANT]  
 >
-> OpenMP in [{SLmetrics}](https://serkor1.github.io/SLmetrics/) is purely experimental, and should be used with caution.
+> OpenMP support in [{SLmetrics}](https://serkor1.github.io/SLmetrics/) is experimental. Use it with caution, as performance gains and stability may vary based on your system configuration and workload.
+
+You can control OpenMP usage within [{SLmetrics}](https://serkor1.github.io/SLmetrics/) using the setUseOpenMP function. Below are examples demonstrating how to enable and disable OpenMP:
+
+```{r}
+# enable OpenMP
+SLmetrics::setUseOpenMP(TRUE)
+
+# disable OpenMP
+SLmetrics::setUseOpenMP(FALSE)
+```
+
+To illustrate the impact of OpenMP on performance, consider the following benchmarks conducted on a 1,000,000 x 200 matrix over 100 iterations[^1].
 
 ### :books: With OpenMP
 
 ```{r With OpenMP, echo = FALSE}
 # 1) extract data;
 DT_ <- DT$OpenMP$TRUE_[,c("n_itr", "median" , "n_gc", "gc/sec", "mem_alloc")]
 DT_$mem_alloc <- round(DT_$mem_alloc/(1024^2))
+DT_$median <- round(DT_$median, 2)
 colnames(DT_) <- column_names
 
-knitr::kable(DT_, caption = "1e6 x 200 matrix", digits = 2)
+knitr::kable(DT_, caption = "1e6 x 200 matrix with OpenMP", digits = 2)
 ```
 
 ### :books: Without OpenMP
@@ -292,9 +310,10 @@ knitr::kable(DT_, caption = "1e6 x 200 matrix", digits = 2)
 # 1) extract data;
 DT_ <- DT$OpenMP$FALSE_[,c("n_itr", "median" , "n_gc", "gc/sec", "mem_alloc")]
 DT_$mem_alloc <- round(DT_$mem_alloc/(1024^2))
+DT_$median <- round(DT_$median, 2)
 colnames(DT_) <- column_names
 
-knitr::kable(DT_, caption = "1e6 x 200 matrix", digits = 2)
+knitr::kable(DT_, caption = "1e6 x 200 matrix without OpenMP", digits = 2)
 ```
 
 ### :books: Installation

diff --git a/README.md b/README.md
@@ -290,24 +290,44 @@ summary(
 
 > \[!IMPORTANT\]
 >
-> OpenMP in [{SLmetrics}](https://serkor1.github.io/SLmetrics/) is
-> purely experimental, and should be used with caution.
+> OpenMP support in [{SLmetrics}](https://serkor1.github.io/SLmetrics/)
+> is experimental. Use it with caution, as performance gains and
+> stability may vary based on your system configuration and workload.
+
+You can control OpenMP usage within
+[{SLmetrics}](https://serkor1.github.io/SLmetrics/) using the
+setUseOpenMP function. Below are examples demonstrating how to enable
+and disable OpenMP:
+
+``` r
+# enable OpenMP
+SLmetrics::setUseOpenMP(TRUE)
+#> OpenMP usage set to: enabled
+
+# disable OpenMP
+SLmetrics::setUseOpenMP(FALSE)
+#> OpenMP usage set to: disabled
+```
+
+To illustrate the impact of OpenMP on performance, consider the
+following benchmarks conducted on a 1,000,000 x 200 matrix over 100
+iterations[^2].
 
 ### :books: With OpenMP
 
-| Iterations | Garbage Collections \[gc()\] | gc() pr. second | Memory Allocation (MB) | NA |
+| Iterations | Runtime (sec) | Garbage Collections \[gc()\] | gc() pr. second | Memory Allocation (MB) |
 |---:|---:|---:|---:|---:|
-| 100 | 0.6426583 | 0 | 0 | 0 |
+| 100 | 0.64 | 0 | 0 | 0 |
 
-RMSE (N = 1e7)
+1e6 x 200 matrix with OpenMP
 
 ### :books: Without OpenMP
 
-| Iterations | Garbage Collections \[gc()\] | gc() pr. second | Memory Allocation (MB) | NA |
+| Iterations | Runtime (sec) | Garbage Collections \[gc()\] | gc() pr. second | Memory Allocation (MB) |
 |---:|---:|---:|---:|---:|
-| 100 | 2.496898 | 0 | 0 | 0 |
+| 100 | 2.5 | 0 | 0 | 0 |
 
-RMSE (N = 1e7)
+1e6 x 200 matrix without OpenMP
 
 ### :books: Installation
 
@@ -342,3 +362,6 @@ By contributing to this project, you agree to abide by its terms.
 
 [^1]: The source code for these benchmarks is available
     [here](https://github.com/serkor1/SLmetrics/blob/main/data-raw/performance.R).
+
+[^2]: The source code for these benchmarks is available
+    [here](https://github.com/serkor1/SLmetrics/blob/main/data-raw/performance.R).