WIP API and bindings unit testing; cleaning up; docs, csv support #204,

#162, #163, #184, #180, #165, #31

.github/workflows/build-and-regression-test.yml

@@ -1,14 +1,94 @@
-name: Build and Regression Test
+name: Build and Unit Test
 
 on:
   push:
     branches: [ master]
   # pull_request:
     # branches: [ master, develop, release ]
 
+env:
+  OMP_NUM_THREADS: 1
+  BUILD_HOME: build
+  TEST_HOME: nrtests
+  PACKAGE_NAME:  vcpkg-export-20220826-200052.1.0.0
+  PKG_NAME: vcpkg-export-20220826-200052
+
 jobs:
-  build:
-    runs-on: ubuntu-latest
+  unit_test:
+    name: Build and unit test
+    runs-on: windows-2019
+    environment: testing
+    defaults:
+      run:
+        shell: cmd
+
+    steps:
+    - name: Checkout repo
+      uses: actions/checkout@v3
+
+    - name: Install boost-test
+      env:
+        REMOTE_STORE: "https://nuget.pkg.github.com/michaeltryby/index.json"
+        USERNAME: michaeltryby
+      run: |
+        nuget sources add -Name github -Source ${{ env.REMOTE_STORE }} -Username ${{ env.USERNAME }} -Password ${{ secrets.ACCESS_TOKEN }}
+        nuget install ${{env.PKG_NAME}} -Source github
+
+    - name: Build
+      env:
+        TOOL_CHAIN_PATH: \scripts\buildsystems\vcpkg.cmake
+      run: |
+        cmake -B .\build -DBUILD_TESTS=ON -DCMAKE_TOOLCHAIN_FILE=.\${{env.PACKAGE_NAME}}${{env.TOOL_CHAIN_PATH}} .
+        cmake --build .\build --config DEBUG
+
+    - name: Unit Test
+      run: ctest --test-dir .\build -C Debug --output-on-failure
+
+
+  reg_test:
+    name: Build and reg test
+    runs-on: windows-2019
+    defaults:
+      run:
+        shell: cmd
+        working-directory: ci-tools/windows
 
     steps:
-    - uses: actions/checkout@v3
+    - name: Checkout swmm repo
+      uses: actions/checkout@v3
+
+    - name: Checkout ci-tools repo
+      uses: actions/checkout@v3
+      with:
+        repository: michaeltryby/ci-tools
+        ref: master
+        path: ci-tools
+
+    - name: Setup python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install requirements
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -r requirements-swmm.txt
+
+    - name: Build
+      run: make.cmd /g "Visual Studio 16 2019"
+
+    - name: Before reg test
+      env:
+        NRTESTS_URL: https://github.com/USEPA/swmm-nrtestsuite
+        BENCHMARK_TAG: v2.5.0-dev
+      run: before-nrtest.cmd ${{ env.BENCHMARK_TAG }}
+
+    - name: Run reg test
+      run: run-nrtests.cmd %GITHUB_RUN_ID%_%GITHUB_RUN_NUMBER%
+
+    - name: Upload artifacts
+      if: ${{ always() }}
+      uses: actions/upload-artifact@v3
+      with:
+        name: build-test-artifacts
+        path: upload/*.*

.github/workflows/build-and-unit-test.yml

@@ -14,14 +14,17 @@ env:
   PKG_NAME: vcpkg-export-20220826-200052
 
 jobs:
-  unit_test:
-    name: Build and unit test
+  engine_unit_test:
+    name: Build and unit test computational engine
+    strategy:
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-13, macos-latest]
+        python-version: [3.11]
     runs-on: windows-2019
     environment: testing
     defaults:
       run:
         shell: cmd
-
     steps:
     - name: Checkout repo
       uses: actions/checkout@v3
@@ -45,7 +48,7 @@ jobs:
       run: ctest --test-dir .\build -C Debug --output-on-failure
 
 
-  reg_test:
+  python_binding_unit_test:
     name: Build and reg test
     runs-on: windows-2019
     defaults:

README.md

@@ -46,40 +46,38 @@ using CMake and the Microsoft Visual Studio C compiler on Windows:
    Readme file resides (which should have 'src' as a sub-directory
    underneath it).
 
-2. Issue the following command to create the directory for storing the built binaries:
+2. Use the following command to create the directory for storing the built binaries:
 
 ```bash
 mkdir build
-cd build
 ```
 
-3. Then enter the following CMake commands to build the binaries:
+3. Then the following CMake commands to build the binaries:
 
 ``` bash
-cmake -G <compiler> .. -A <platform>
+cmake -G <compiler> .. -A <platform> -B .\build
 cmake --build . --config Release
 ```
 
-where `<compiler>` is the name of the Visual Studio compiler being used
+where `<compiler>` is the name of the compiler being used
 in double quotes (e.g., "Visual Studio 15 2017", "Visual Studio 16 2019",
-or "Visual Studio 17 2022") and `<platform>` is Win32 for a 32-bit build 
-or x64 for a 64-bit build. The resulting engine DLL (swmm5.dll), command 
-line executable (runswmm.exe), and output processing libraries (swmm-output.dll)
+or "Visual Studio 17 2022") and `<platform>` (e.g., Win32 for a 32-bit build 
+or x64 for a 64-bit build). The resulting engine shared libraries (i.e., swmm5.dll), command line executable (i.e., runswmm.exe), and output processing libraries (i.e., swmm-output.dll)
 will appear in the build\Release directory.
 
 For other platforms, such as Linux or MacOS, Step 3 can be replaced with:
 
 ```bash
-cmake ..
-cmake --build .
+cmake .
+cmake --build .\build
 ```
 
 The resulting shared object library (libswmm5.so or libswmm5.dylib) and 
-command line executable (runswmm) will appear in the build directory. 
+command line executable (runswmm) will be compiled to the build directory. 
 
 ### Python Bindings (Experimental)
 
-Experimental python bindings for the SWMM API are being developed to support regression and benchmark testing as well as other applications. _**These bindings are still under development and testing and has yet to be cleared through US EPA ORD's official quality assurance review process**_. The exprimental python bindings can be built and installed locally using the following command.
+Experimental python bindings for the SWMM API are being developed to support regression and benchmark testing as well as for other applications. _**These bindings are still under development and testing and has yet to be cleared through US EPA ORD's official quality assurance review process**_. The exprimental python bindings can be built and installed locally using the following command.
 
 ```bash
 cd python

python/MANIFEST.in

@@ -1,11 +1,11 @@
 include LICENSE
 include README.md
-recursive-include *.py
-recursive-include *.txt
-recursive-include *.md
-recursive-include *.pyi
-recursive-include *.inp
-recursive-include *.pickle
+recursive-include . *.py
+recursive-include . *.txt
+recursive-include . *.md
+recursive-include . *.pyi
+recursive-include . *.inp
+recursive-include . *.pickle
 recursive-include docs *.rst
 recursive-include tests *.csv
 global-exclude *.pyc

python/epaswmm/output/_output.pyi

@@ -267,13 +267,13 @@ class Output:
 
     def __init__(self, output_file: str) -> None:
         """
-        Constructor to initialize the SWMM output file instance.
+        Constructor to open the SWMM output file.
 
         :param output_file: Path to the SWMM output file.
         :type output_file: str
         """
         ...
-
+    
     def __enter__(self): # -> Self@Output:
         """
         Method to return the SWMM output file instance.
@@ -356,7 +356,7 @@ class Output:
         """
         ...
 
-    def get_time_attribute(self, time_atrribute: int) -> int:
+    def get_time_attribute(self, time_attribute: TimeAttribute) -> int:
         """
         Method to get the temporal attributes of the simulation in the SWMM output file.
 
@@ -365,7 +365,7 @@ class Output:
         """
         ...
 
-    def get_element_name(self, element_type: int, element_index: int) -> str:
+    def get_element_name(self, element_type: ElementType, element_index: int) -> str:
         """
         Method to get the name of an element in the SWMM output file.
 
@@ -378,7 +378,7 @@ class Output:
         """
         ...
 
-    def get_element_names(self, element_type: int) -> list:
+    def get_element_names(self, element_type: ElementType) -> List[str]:
         """
         Method to get the names of all elements of a given type in the SWMM output file.
 
@@ -389,7 +389,7 @@ class Output:
         """
         ...
 
-    def get_subcatchment_timeseries(self, element_index: int, attribute: int, start_date_index: int = ..., end_date_index: int = ...) -> dict:
+    def get_subcatchment_timeseries(self, element_index: int, attribute: SubcatchAttribute, start_date_index: int = ..., end_date_index: int = ...) -> Dict[datetime, float]:
         """
         Method to get the time series data for a subcatchment attribute in the SWMM output file.
 
@@ -407,7 +407,7 @@ class Output:
         """
         ...
 
-    def get_node_timeseries(self, element_index: int, attribute: int, start_date_index: int = ..., end_date_index: int = ...) -> dict:
+    def get_node_timeseries(self, element_index: int, attribute: NodeAttribute, start_date_index: int = ..., end_date_index: int = ...) -> Dict[datetime, float]:
         """
         Method to get the time series data for a node attribute in the SWMM output file.
 
@@ -424,7 +424,7 @@ class Output:
         """
         ...
 
-    def get_link_timeseries(self, element_index: int, attribute: int, start_date_index: int = ..., end_date_index: int = ...) -> dict:
+    def get_link_timeseries(self, element_index: int, attribute: LinkAttribute, start_date_index: int = ..., end_date_index: int = ...) -> Dict[datetime, float]:
         """
         Method to get the time series data for a link attribute in the SWMM output file.
 
@@ -441,7 +441,7 @@ class Output:
         """
         ...
 
-    def get_system_timeseries(self, attribute: int, start_date_index: int = ..., end_date_index: int = ...) -> dict:
+    def get_system_timeseries(self, attribute: SystemAttribute, start_date_index: int = ..., end_date_index: int = ...) -> Dict[datetime, float]:
         """
         Method to get the time series data for a system attribute in the SWMM output file.
 
@@ -456,7 +456,7 @@ class Output:
         """
         ...
 
-    def get_subcatchment_values_by_time_and_attribute(self, time_index: int, attribute: int) -> dict:
+    def get_subcatchment_values_by_time_and_attribute(self, time_index: int, attribute: SubcatchAttribute) -> Dict[str, float]:
         """
         Method to get the subcatchment values for all subcatchments for a given time index and attribute.
 
@@ -469,7 +469,7 @@ class Output:
         """
         ...
 
-    def get_node_values_by_time_and_attribute(self, time_index: int, attribute: int) -> dict:
+    def get_node_values_by_time_and_attribute(self, time_index: int, attribute: NodeAttribute) -> Dict[str, float]:
         """
         Method to get the node values for all nodes for a given time index and attribute.
 
@@ -482,7 +482,7 @@ class Output:
         """
         ...
 
-    def get_link_values_by_time_and_attribute(self, time_index: int, attribute: int) -> dict:
+    def get_link_values_by_time_and_attribute(self, time_index: int, attribute: LinkAttribute) -> Dict[str, float]:
         """
         Method to get the link values for all links for a given time index and attribute.
 
@@ -495,7 +495,7 @@ class Output:
         """
         ...
 
-    def get_system_values_by_time_and_attribute(self, time_index: int, attribute: int) -> dict:
+    def get_system_values_by_time_and_attribute(self, time_index: int, attribute: SystemAttribute) -> Dict[str, float]:
         """
         Method to get the system values for a given time index and attribute.
         
@@ -508,7 +508,7 @@ class Output:
         """
         ...
 
-    def get_subcatchment_values_by_time_and_element_index(self, time_index: int, element_index: int) -> dict:
+    def get_subcatchment_values_by_time_and_element_index(self, time_index: int, element_index: int) -> Dict[str, float]:
         """
         Method to get all attributes of a given subcatchment for specified time.
 
@@ -521,7 +521,7 @@ class Output:
         """
         ...
 
-    def get_node_values_by_time_and_element_index(self, time_index: int, element_index: int) -> dict:
+    def get_node_values_by_time_and_element_index(self, time_index: int, element_index: int) -> Dict[str, float]:
         """
         Method to get all attributes of a given node for specified time.
 
@@ -534,7 +534,7 @@ class Output:
         """
         ...
 
-    def get_link_values_by_time_and_element_index(self, time_index: int, element_index: int) -> dict:
+    def get_link_values_by_time_and_element_index(self, time_index: int, element_index: int) -> Dict[str, float]:
         """
         Method to get all attributes of a given link for specified time.
 
@@ -548,7 +548,7 @@ class Output:
         """
         ...
 
-    def get_system_values_by_time(self, time_index: int) -> dict:
+    def get_system_values_by_time(self, time_index: int) -> Dict[str, float]:
         """
         Method to get all attributes of the system for specified time.