Add OMEGA Broadcast functions (#36)

Adds OMEGA Broadcast functions

This PR adds OMEGA broadcasting functions with documentation.
* implements blocking broadcast functions
* adds testings for the functions
* adds user-guide and developer-guide

fixed the issues found during PR-review:

* properly use MasterRank in MachEnv instead of rank=0
* renamed variable names to match with Clang style
* updated document accordingly
* moved Broadcast from infra to base directory
* moved Broadcast mode from infra to base directory
* fixed bugs in document

components/omega/create_scripts.py

@@ -348,7 +348,7 @@ def generate_scripts(self, outvar):
             f.write("#!/usr/bin/env bash\n\n")
 
             f.write("source ./omega_env.sh\n")
-            f.write("ctest # --rerun-failed --output-on-failure\n")
+            f.write("ctest $* # --rerun-failed --output-on-failure\n")
 
         st = os.stat(omega_env)
         os.chmod(omega_env, st.st_mode | stat.S_IEXEC)

components/omega/doc/design/Broadcast.md

@@ -47,7 +47,7 @@ function with simplified arguments.
 
 ### 4.1 Data types and parameters
 
-For non-blocking broadcasts, we will alias the MPI_request type
+For non-blocking broadcasts, we will alias the `MPI_request` type
 to a Broadcast ID:
 
 ```c++
@@ -67,15 +67,15 @@ The first form is the simplest for a broadcast within the default
 environment and from the master task:
 
 ```c++
-int Broadcast([data type] value);
+int Broadcast([data type] Value);
 ```
 
 where `[data type]` is one of the supported types (I4, I8 R4, R8, Real,
 boolean, std::string). In actual use, this would look like:
 
 ```c++
-ierr = Broadcast(myIntVar);
-ierr = Broadcast(myRealVar);
+int Err = Broadcast(MyIntValue);
+int Err = Broadcast(MyRealValue);
 [etc for all data types]
 ```
 
@@ -88,8 +88,8 @@ This is similar to the above, but adds the additional argument
 for the source rank to broadcast from.
 
 ```c++
-int Broadcast([data type] value,  ///< [in] value to be broadcast
-              const int srcRank   ///< [in] rank to broadcast from
+int Broadcast([data type] Value,  ///< [in] value to be broadcast
+              const int SrcRank   ///< [in] rank to broadcast from
               );      //
 ```
 
@@ -98,8 +98,8 @@ int Broadcast([data type] value,  ///< [in] value to be broadcast
 As in 4.2.1, but adds the machine environment as an argument:
 
 ```c++
-int Broadcast([data type] value,    ///< [in] value to be broadcast
-              const MachEnv subEnv, ///< [in] defined OMEGA environment
+int Broadcast([data type] Value,     ///< [in] value to be broadcast
+              const MachEnv *SubEnv, ///< [in] defined OMEGA environment
               );
 ```
 
@@ -108,9 +108,9 @@ int Broadcast([data type] value,    ///< [in] value to be broadcast
 As in 4.2.2, but adds the machine environment as an argument:
 
 ```c++
-int Broadcast([data type] value,     ///< [in] value to be broadcast
-              const MachEnv subEnv,  ///< [in] defined OMEGA environment
-              const int srcRank      ///< [in] rank to broadcast from
+int Broadcast([data type] Value,     ///< [in] value to be broadcast
+              const MachEnv *SubEnv, ///< [in] defined OMEGA environment
+              const int SrcRank      ///< [in] rank to broadcast from
               );
 ```
 
@@ -128,9 +128,9 @@ included to wait for the request to complete. A non-blocking
 sequence would look like:
 
 ```c++
-BroadcastID myReqID = IBroadcast(myVar);
+BroadcastID myReqID = IBroadcast(MyVar);
 [ perform other tasks/computation ]
-int err = IBroadcastWait(myReqID);
+int Err = IBroadcastWait(MyReqID);
 ```
 
 ## 5 Verification and Testing

components/omega/doc/devGuide/Broadcast.md

@@ -0,0 +1,34 @@
+(omega-dev-broadcast)=
+
+# Omega Broadcast
+
+## Code Structure
+
+Omega Broadcasting functions are organized within two primary files:
+
+1. **Header File**: Located at `src/base/Broadcast.h`, this file declares
+   various functions of the `Broadcast`. These functions are
+   distinctively overloaded to accommodate multiple broadcasting needs.
+   The key differentiators for these overloads are based on:
+    - The types of variables being broadcasted.
+    - The specific ordering of function arguments.
+
+2. **Implementation File**: The actual implementations of these declared
+   functions are found in `src/base/Broadcast.cpp`.
+
+## IBroadcast Interface
+
+Parallel to `Broadcast`, there is the `IBroadcast` interface. Currently under
+development, `IBroadcast` focuses on overloading functions for non-blocking
+broadcast operations. This aspect of the Omega Broadcasting system is
+designed to provide more efficient and asynchronous communication capabilities.
+
+## Integration with MPI
+
+At their core, the Omega broadcast functions serve as wrappers around
+the MPI (Message Passing Interface) broadcast functions. They are
+intricately designed to:
+- Retrieve values from the Omega Environment.
+- Utilize Omega-specific data types.
+- Seamlessly feed these values into the standard MPI functions for
+effective broadcasting.

components/omega/doc/index.md

@@ -24,6 +24,7 @@ userGuide/QuickStart
 userGuide/OmegaBuild
 userGuide/DataTypes
 userGuide/MachEnv
+userGuide/Broadcast
 userGuide/Logging
 ```
 
@@ -34,6 +35,7 @@ userGuide/Logging
 devGuide/QuickStart
 devGuide/DataTypes
 devGuide/MachEnv
+devGuide/Broadcast
 devGuide/CondaEnv
 devGuide/Linting
 devGuide/Docs

components/omega/doc/userGuide/Broadcast.md

@@ -0,0 +1,97 @@
+(omega-user-broadcast)=
+
+# Omega Broadcast
+
+## Broadcasting Functions
+
+Omega's broadcasting functions offer developers a streamlined method for
+disseminating scalar and array values among MPI tasks. These functions are
+categorized into two types: Blocking and Non-blocking.
+
+### Blocking Broadcasting Functions
+
+When it comes to MPI broadcast operations, a blocking broadcast would imply
+that the function call to broadcast data to all processes in a group does
+not return until the data has been sent and correctly received by all the
+target processes.
+
+### Including the Broadcasting Functions in Your Code
+
+To leverage Omega's broadcasting functions, you must include the Broadcast.h
+header file in your source code:
+
+```c
+#include "Broadcast.h"
+```
+
+### Broadcasting Scalar or Array Values
+
+For broadcasting either scalar or array values, utilize the Broadcast
+function as demonstrated below:
+
+```c
+OMEGA::I4 MyVal = 1;
+
+// Broadcasting from the master task
+OMEGA::Broadcast(MyVal);
+```
+The above example illustrates the broadcasting of an OMEGA::I4 type scalar
+value from the master task of the default Omega environment.
+
+### Specifying broadcasting task and/or environment in Omega
+
+For developers seeking to modify the sending task or the Omega environment
+during broadcasting, Omega offers flexible syntax options. These additional
+arguments to the Broadcast function enable customization, while maintaining
+the simplicity of the basic broadcasting operation.
+
+```c
+OMEGA::I4 MyVal      = 1;
+const int RootTask   = 1;
+
+// Get a specific Omega Machine Environment
+OMEGA::MachEnv *SubsetEnv = OMEGA::MachEnv::getEnv("Subset");
+
+// broadcast from the master task of SubsetEnv environment
+OMEGA::Broadcast(MyVal, SubsetEnv);
+
+// broadcast from task 1 of SubsetEnv environment
+OMEGA::Broadcast(MyVal, SubsetEnv, RootTask);
+
+// broadcast from task 1 of the default environment
+OMEGA::Broadcast(MyVal, RootTask);
+```
+
+### Broadcasting Array Values
+
+The syntax for broadcasting arrays is analogous to that used
+for scalar values:
+
+```c
+std::vector<OMEGA::R8> MyVector;
+
+for (int i = 1; i <= 5; i++) {
+    MyVector.push_back(1.0);
+}
+
+OMEGA::Broadcast(MyVector, RootTask);
+```
+
+This example shows how to broadcast an array of OMEGA::R8 type values,
+specifying the root task for broadcasting.
+
+### Supported Data Types for Broadcasting
+
+The Broadcast functions are compatible with the following data types:
+
+* `OMEGA::I4`
+* `OMEGA::I8`
+* `OMEGA::R4`
+* `OMEGA::R8`
+* `bool`
+* `std::string` (NOTE: array of strings are not supported)
+
+## Non-blocking Broadcasting Functions
+
+This feature is currently under development and will offer asynchronous
+broadcasting capabilities.

components/omega/src/CMakeLists.txt

@@ -1,12 +1,12 @@
 # build Omega
 
 # Add source files for the library
-file(GLOB _LIBSRC_FILES base/*.cpp infra/*.cpp ocn/*.cpp)
+file(GLOB _LIBSRC_FILES infra/*.cpp base/*.cpp ocn/*.cpp)
 
 # Create the library target
 add_library(${OMEGA_LIB_NAME} ${_LIBSRC_FILES})
 
-# add include directories
+# add compiler options
 target_compile_options(
     ${OMEGA_LIB_NAME}
     PRIVATE
@@ -15,6 +15,7 @@ target_compile_options(
      ${OMEGA_CXX_FLAGS}
 )
 
+# add linker options
 target_link_options(
     ${OMEGA_LIB_NAME}
     PRIVATE