Updates on READMEs and examples

README.md

@@ -1,4 +1,4 @@
-# HydroCompute - a computational library for hydrology
+# HydroCompute - a web-based client-side computational library for hydrology
 
 ## Table of Contents
 
@@ -15,7 +15,7 @@
 * [References](#references)
 
 ## Introduction
-This work introduces hydroCompute, a computational library for hydrology and environmental sciences that runs on the client side. It employes 4 different engines, 3 main computations and 1 for peer-to-peer connection. The library has been developed using ES6 standards and the most recent available APIs for WebAssembly, WebGPU, WebRTC, and the Web Workers specifications.
+This work introduces HydroCompute, a computational library for hydrology and environmental sciences that runs on the client side. It employes 4 different engines, 3 main computations and 1 for peer-to-peer connection. The library has been developed using ES6 standards and the most recent available APIs for WebAssembly, WebGPU, WebRTC, and the Web Workers specifications.
 
 ## How to Use
 Please download the library and run `index.html`. If a new html file should be created, the library must be onloaded onto the file as a script
@@ -33,7 +33,11 @@ The library is loaded into an HTML web app by declaring either it as a window ob
 const compute = new hydrocompute('engineName');
 ```
 
-When instantiated if no specific engines are passed into the constructor, the library will default to run using the functions within the JavaScript engine. You can see all the available functions in for each of the functions in the following pages:
+When instantiated if no specific engines are passed into the constructor, the library will default to run using the functions within the JavaScript engine. The available engines along with existing code and how to develop more functions for usage in the library can be found in the following links:
+
+* [WebAssembly](https://github.com/uihilab/HydroCompute/tree/master/src/wasm): Available C and AssemblyScript bindings.
+* [JavaScript](https://github.com/uihilab/HydroCompute/tree/master/src/javascript): Available as native JavaScript object.
+* [WebGPU](https://github.com/uihilab/HydroCompute/tree/master/src/webgpu): GLSL code onloaded as strings in a JavaScript object.
 
 ### Running a simulation
 
@@ -75,6 +79,8 @@ compute.availableResults()
 ```
 The results per simulation will be saved with nametag `Simulation_N`.
 
+A list of case studies and examples can be found [here](https://github.com/uihilab/HydroCompute/tree/master/examples).
+
 ## Expansions and Test Cases
 ### Expansions
 Currently the library works fully with Chromium based browsers. Mozilla implementations will be added in future releases.
@@ -90,15 +96,19 @@ It is possible for the library to expand by becoming a community-based framework
 Please feel free to send feedback to us on any issues found by filing an issue.
 
 ## Scalability and To-Do's
-New engines and functions for the existing engines will be added into the library for easier implementation and usage.
+The HydroCompute library is a work in progress that aims in providing a scalable set of tools so that the hydrologic community can benefit from. To this extent, we have the following open developments that will be included in future deployments:
+
+* New engines and functions for the existing engines will be added into the library for easier implementation and usage.
+* A webpack implementation of the library that provides an easier interaction directly from a CDN.
+* Create a better integration with technologies such as Docker containers to streamline the deployment of new functions using WebAssembly into the library.
 
 
 ## License
 This project is licensed under the MIT License - see the [LICENSE](https://github.com/uihilab/HydroCompute/blob/master/LICENSE) file for details.
 
 ## Acknowledgements
-This work was funded by the University of Iowa's HydroInformatics Lab.
+This project was funded by the National Oceanic & Atmospheric Administration (NOAA) via a cooperative agreement with The University of Alabama (NA22NWS4320003) awarded to the Cooperative Institute for Research to Operations in Hydrology (CIROH).
 
 ## References
 
-* Erazo Ramirez, C., Sermet, Y., & Demir, I. (2023a). Hydrocompute: An Open-Source Web-Based Computational Library for Hydrology and Environmental Sciences. EarthArxiv. https://doi.org/10.31223/X5FM2D 
+* Erazo Ramirez, C., Sermet, Y., & Demir, I. (2023). Hydrocompute: An Open-Source Web-Based Computational Library for Hydrology and Environmental Sciences. EarthArxiv. https://doi.org/10.31223/X5FM2D 

examples/README.md

@@ -0,0 +1,11 @@
+## HydroCompute Case Studies and Examples
+
+This is a list of case studies used for testing development of the library and additional information on the library usage.
+
+The current case studies are the following:
+
+* **[Case Study 1](https://github.com/uihilab/HydroCompute/tree/master/examples/case-study1)**: Matrix multiplication on different engines and data sizes.
+* **[Case Study 2](https://github.com/uihilab/HydroCompute/tree/master/examples/case-study2)**: Streamflow forecasting web application
+* **[Case Study 3](https://github.com/uihilab/HydroCompute/tree/master/examples/case-study3)**: Dashboard for statistical analysis
+
+Further examples and case studies will be added to this list.

workshop/case-study-3/README.md → examples/case-study-3/README.md

@@ -1,18 +1,18 @@
 ## Dashboard for statistical analysis
-This example aims to create a live preview for USGS derived streamflow stations across the Salt Lake City Area.
+This example aims to create a live preview for USGS derived streamflow stations across the Salt Lake City Area used in CIROH developer's conference 2023.
 
 ## Features
-* Data Retrieval: Downloading and cleaning data using HydroLang.
-* Data Analysis: Do statistic analysis using HydroCompute.
-* Visualization and downloading: Using HydroLang for visualizing data and model outputs and downloading data.
+* **Data Retrieval**: Downloading and cleaning data using HydroLang.
+* **Data Analysis**: Do statistic analysis using HydroCompute.
+* **Visualization and downloading**: Using HydroLang for visualizing data and model outputs and downloading data.
 
 ## Getting Started
 To run this web application locally:
 
 * Clone this repository to your local machine.
 Open the index.html file in a web browser.
 
-Note: open the Developer Tools to see outputs from the HydroCompute.
+Note: open the Developer Tools to see additional outputs from the HydroCompute.
 
 ## Contributing
 Contributions to enhance features, fix bugs, or improve the user interface are welcome. Please follow the guidelines outlined in the CONTRIBUTING.md file.

workshop/case-study-3/index.html → examples/case-study-3/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
 
 <head>
-    <script src="https://cdn.jsdelivr.net/npm/[email protected].7/hydrolang.js">
+    <script src="https://cdn.jsdelivr.net/npm/[email protected].8/hydrolang.js">
     </script>
     <script type="module" src="../../src/hydrocompute.js" onload="loadCompute()">
     </script>

examples/case-study1/README.md

@@ -0,0 +1,89 @@
+# Case Study 1: Matrix Multiplication
+
+This codebase contains a matrix multiplication case study, showcasing the capabilities of the HydroCompute framework.
+
+## Features
+
+- **Matrix Size Representation**: Matrix sizes per subcase are denoted as the power of 2 for each value.
+- **SubCase 1**: Matrices of sizes [256, 6561, 10000, 38416, 65536, 194481, 390625, 531441, 1048576]
+- **SubCase 2_A**: Matrices of sizes [256, 6561, 10000, 38416, 65536, 194481]
+- **SubCase 2_B**: Matrices of sizes [390625, 531441, 1048576, 5764801, 11390625]
+- **SubCase 3**: Matrices of sizes [1048576, 2313441, 5308416, 7890481, 10556001, 13845841, 15752961, 16777216, 18974736, 20151121, 24010000, 28398241, 31640625]
+- **HydroCompute Instance**: The framework is initialized using the HydroCompute class.
+
+## Getting Started
+To run this web application locally:
+
+* Clone this repository to your local machine.
+Open the index.html file in a web browser.
+* Open the Developer Tools to see outputs from the HydroCompute.
+* Copy-paste each execution code below in the console of the browser.
+
+## Execution
+
+1. **Data Generation**:
+
+For each matrix in the subcase, random data is generated and stored in the HydroCompute local space.
+```js
+// Define the hydrocompute instance
+const compute = new hydroCompute();
+
+// Put the name of the subcase to save in the compute local space
+for (let matrix of subcase) {
+    compute.data({
+        id: JSON.stringify(matrix), 
+        data: compute.utils.genRandomData(matrix, 1000, 2)
+    });
+}
+```
+
+2. **Subcase 1**:
+
+Running small and large matrices on all engines (JS, WASM-C, WebGPU).
+```js
+// Subcase 1: Running small and large matrices on all engines
+// For each engine, the name of the function changes. You need to switch engine and change the name on the variable. Engine change: "javascript", "wasm", "webgpu" 
+compute.setEngine("javascript");
+// JavaScript: 'matrixMultiply_js', WASM-C: '_matrixMultiply_c', WebGPU: 'matrixMultiply_gpu' 
+
+let functions = ['matrixMultiply_js'];
+compute.run({
+    functions: ['matrixMultiply_js'],
+    dataIds: subCase1
+});
+```
+3. **Subcase 2**:
+
+Running matrices on SubCase2_A and SubCase2_B.
+```js
+// Subcase 2: A-2000, 4000, 8000, 16000 on subCase2_A; B- 100, 200, 400 on subCase2_B
+
+// Define the same structure with the same name repeated N number of threads 
+let functions = new Array(2000).fill('matrixMultiply_js')
+compute.run({
+    functions,
+    dataIds: subCase2_A // or subCase2_B
+});
+```
+
+4. **Subcase 3**:
+
+Running very large matrices on a single Web Worker using WebGPU
+
+```js
+compute.setEngine("webgpu");
+let functions = ['matrixMultiply_gpu'];
+compute.run({
+    functions,
+    dataIds: subCase3
+});
+```
+
+*Note: The code is found in the file called matrixMul.js.*
+
+## License
+This project is licensed under the MIT License.
+
+
+
+

examples/case-study1/index.html

@@ -9,7 +9,7 @@
     <title>Case Study 1: Matrix Multiplication</title>
 </head>
 <body>
-    <h2>Case Study 2: Matrix Multiplication</h2>
+    <h2>Case Study 1: Matrix Multiplication</h2>
     <p>
         Please open up the browser's console and copy-paste code according to the definitions for each subcase in the matrixMult.js file.
     </p>

examples/case-study2/README.md

@@ -1,10 +1,10 @@
-## Streamflow Forecasting Web Application
+## Case Study 2: Streamflow Forecasting Web Application
 This web application is designed for streamflow forecasting analysis within different counties of Iowa. It allows users to retrieve, analyze, and visualize on-the-fly streamflow data from various data sources using a user-friendly interface.
 
 ## Features
-* Data Retrieval: Users can select different data sources, counties, and stations to retrieve streamflow data using HydroLang.
-* Data Analysis: The application performs various analyses including simple moving average, exponential moving average, time series autocorrelation, linear detrending, ARMA parameter calculation, etc., on the retrieved data using HydroCompute.
-* Visualization: The analysis results are visualized using Google Charts through HydroLang, providing graphical representations of the forecasted streamflow data.
+* **Data Retrieval**: Users can select different data sources, counties, and stations to retrieve streamflow data using HydroLang.
+* **Data Analysis**: The application performs various analyses including simple moving average, exponential moving average, time series autocorrelation, linear detrending, ARMA parameter calculation, etc., on the retrieved data using HydroCompute.
+* **Visualization**: The analysis results are visualized using Google Charts through HydroLang, providing graphical representations of the forecasted streamflow data.
 
 ## Getting Started
 To run this web application locally:
@@ -16,11 +16,11 @@ Note: open the Developer Tools to see outputs from the HydroCompute.
 Live preview [here](https://hydroinformatics.uiowa.edu/lab/hydrosuite/hydrocompute/cs2).
 
 ## Usage
-* Select Data Source: Choose from available data sources such as 'MOPEX', 'NOAA GHCN', 'Global Rivers', and 'USGS Daily Values'. Note: USGS fully functional.
-* Choose County and Stations: Select a county from the dropdown menu and choose specific stations for data retrieval.
-* Retrieve Data: Click on "Retrieve Stations" to initiate the data retrieval process.
+* **Select Data Source**: Choose from available data sources such as 'MOPEX', 'NOAA GHCN', 'Global Rivers', and 'USGS Daily Values'. Note: USGS fully functional.
+* **Choose County and Stations**: Select a county from the dropdown menu and choose specific stations for data retrieval.
+* **Retrieve Data**: Click on "Retrieve Stations" to initiate the data retrieval process.
 View Analysis and Results: The retrieved data is analyzed and displayed under the "Analysis and Results" section.
-* Visualize Results: Use the dropdowns to select specific stations and date ranges to visualize the computed results using Google Charts.
+* **Visualize Results**: Use the dropdowns to select specific stations and date ranges to visualize the computed results using Google Charts.
 
 ## Dependencies
 * Bootstrap: CSS framework for styling the web page.

src/wasm/modules/C/arima_c/arima_c.c

@@ -1,19 +1,46 @@
+/**
+ * @brief Implementation of statistical operations for web assembly.
+ *
+ * This program provides functions for statistical operations such as linear detrending,
+ * auto-updating parameter ARMA model, setting parameters for ARMA model, autocorrelation function (ACF),
+ * partial autocorrelation function (PACF), and Box-Cox transformation. It also includes memory
+ * management functions for creating and destroying memory.
+ *
+ */
 #include <emscripten.h>
 #include <math.h>
 #include <stdlib.h>
 #include <stdint.h>
 #include <stdio.h>
 
+/**
+ * @brief Allocates memory of a specified size.
+ *
+ * @param size The size of the memory to allocate.
+ * @return A pointer to the allocated memory.
+ */
 EMSCRIPTEN_KEEPALIVE
 uint8_t* createMem(int size) {
 	return malloc(size);
 }
 
+/**
+ * @brief Deallocates the memory pointed to by the given pointer.
+ *
+ * @param p A pointer to the memory to be deallocated.
+ */
 EMSCRIPTEN_KEEPALIVE
 void destroy(uint8_t* p){
 	free(p);
 }
 
+/**
+ * @brief Performs linear detrending on the input data.
+ *
+ * @param data The input data.
+ * @param result The detrended data.
+ * @param n The size of the data.
+ */
 EMSCRIPTEN_KEEPALIVE
 void linear_detrend(float *data, float *result, int n) {
     float x_mean = 0.0;
@@ -46,6 +73,13 @@ void linear_detrend(float *data, float *result, int n) {
     }
 }
 
+/**
+ * @brief Auto-updates parameters for the ARMA model.
+ *
+ * @param data The input data.
+ * @param prediction The predicted data.
+ * @param n The size of the data.
+ */
 EMSCRIPTEN_KEEPALIVE
 // autoupdate parameter ARMA model
 void arima_autoParams(float *data, float *prediction, int n) {
@@ -145,6 +179,13 @@ void arima_autoParams(float *data, float *prediction, int n) {
     }
 }
 
+/**
+ * @brief Sets parameters for the ARMA model.
+ *
+ * @param data The input data.
+ * @param prediction The predicted data.
+ * @param m The size of the data.
+ */
 EMSCRIPTEN_KEEPALIVE
 // autoupdate parameter ARMA model
 void arima_setParams(float *data, float *prediction, int m) {
@@ -169,7 +210,13 @@ void arima_setParams(float *data, float *prediction, int m) {
     }
 }
 
-
+/**
+ * @brief Computes the autocorrelation function (ACF) for the input data.
+ *
+ * @param data The input data.
+ * @param result The computed ACF.
+ * @param n The size of the data.
+ */
 EMSCRIPTEN_KEEPALIVE
 // total autocorrelation function
 void acf(float *data, float *result, int n) {
@@ -199,6 +246,13 @@ void acf(float *data, float *result, int n) {
     result[0] /= 2;
 }
 
+/**
+ * @brief Computes the partial autocorrelation function (PACF) for the input data.
+ *
+ * @param x The input data.
+ * @param pacf_result The computed PACF.
+ * @param n The size of the data.
+ */
 EMSCRIPTEN_KEEPALIVE
 // partial autocorrelation function with max lag of 75
 void pacf(float *x, float *pacf_result, int n) {
@@ -290,6 +344,13 @@ void pacf(float *x, float *pacf_result, int n) {
     }
 }
 
+/**
+ * @brief Applies the Box-Cox transformation on the input data.
+ *
+ * @param data The input data.
+ * @param result The transformed data.
+ * @param n The size of the data.
+ */
 EMSCRIPTEN_KEEPALIVE
 void boxcox_transform(float* data, float* result, int n) {
 	float lambda = 0.5;