Skip to content

Commit 2a6acde

Browse files
cbuahincbuahin
committedNov 22, 2024
WIP finalizing core api; consolidating readme; #204, #162, #163, #184, #180 
1 parent 53f9909 commit 2a6acde

31 files changed

+873
-271
lines changed
 

‎.github/workflows/build-and-deploy.yml

Whitespace-only changes.

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

Whitespace-only changes.

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

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
name: Build and Unit Test
2+
3+
on:
4+
push:
5+
branches: [ master, develop, release ]
6+
# pull_request:
7+
# branches: [ master, develop, release ]
8+
9+
env:
10+
OMP_NUM_THREADS: 1
11+
BUILD_HOME: build
12+
TEST_HOME: nrtests
13+
PACKAGE_NAME: vcpkg-export-20220826-200052.1.0.0
14+
PKG_NAME: vcpkg-export-20220826-200052
15+
16+
jobs:
17+
unit_test:
18+
name: Build and unit test
19+
runs-on: windows-2019
20+
environment: testing
21+
defaults:
22+
run:
23+
shell: cmd
24+
25+
steps:
26+
- name: Checkout repo
27+
uses: actions/checkout@v3
28+
29+
- name: Install boost-test
30+
env:
31+
REMOTE_STORE: "https://nuget.pkg.github.com/michaeltryby/index.json"
32+
USERNAME: michaeltryby
33+
run: |
34+
nuget sources add -Name github -Source ${{ env.REMOTE_STORE }} -Username ${{ env.USERNAME }} -Password ${{ secrets.ACCESS_TOKEN }}
35+
nuget install ${{env.PKG_NAME}} -Source github
36+
37+
- name: Build
38+
env:
39+
TOOL_CHAIN_PATH: \scripts\buildsystems\vcpkg.cmake
40+
run: |
41+
cmake -B .\build -DBUILD_TESTS=ON -DCMAKE_TOOLCHAIN_FILE=.\${{env.PACKAGE_NAME}}${{env.TOOL_CHAIN_PATH}} .
42+
cmake --build .\build --config DEBUG
43+
44+
- name: Unit Test
45+
run: ctest --test-dir .\build -C Debug --output-on-failure
46+
47+
48+
reg_test:
49+
name: Build and reg test
50+
runs-on: windows-2019
51+
defaults:
52+
run:
53+
shell: cmd
54+
working-directory: ci-tools/windows
55+
56+
steps:
57+
- name: Checkout swmm repo
58+
uses: actions/checkout@v3
59+
60+
- name: Checkout ci-tools repo
61+
uses: actions/checkout@v3
62+
with:
63+
repository: michaeltryby/ci-tools
64+
ref: master
65+
path: ci-tools
66+
67+
- name: Setup python
68+
uses: actions/setup-python@v4
69+
with:
70+
python-version: '3.11'
71+
72+
- name: Install requirements
73+
run: |
74+
python -m pip install --upgrade pip
75+
python -m pip install -r requirements-swmm.txt
76+
77+
- name: Build
78+
run: make.cmd /g "Visual Studio 16 2019"
79+
80+
- name: Before reg test
81+
env:
82+
NRTESTS_URL: https://github.com/USEPA/swmm-nrtestsuite
83+
BENCHMARK_TAG: v2.5.0-dev
84+
run: before-nrtest.cmd ${{ env.BENCHMARK_TAG }}
85+
86+
- name: Run reg test
87+
run: run-nrtests.cmd %GITHUB_RUN_ID%_%GITHUB_RUN_NUMBER%
88+
89+
- name: Upload artifacts
90+
if: ${{ always() }}
91+
uses: actions/upload-artifact@v3
92+
with:
93+
name: build-test-artifacts
94+
path: upload/*.*

‎Build.md

-34
This file was deleted.

‎README.md

+113-10
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,123 @@
1-
ORD Stormwater-Management-Model Solver
2-
==================================
3-
4-
Stormwater Management Model (SWMM) computational engine
1+
EPA ORD Stormwater Management Model (SWMM)
2+
==========================================
53

4+
Stormwater Management Model (SWMM) computational engine and output post-processing codebase
65

76
## Build Status
8-
[![Build and Test](https://github.com/USEPA/Stormwater-Management-Model/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/USEPA/Stormwater-Management-Model/actions/workflows/build-and-test.yml)
9-
10-
## Disclaimer
11-
The United States Environmental Protection Agency (EPA) GitHub project code is provided on an "as is" basis and the user assumes responsibility for its use. EPA has relinquished control of the information and no longer has responsibility to protect the integrity, confidentiality, or availability of the information. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by EPA. The EPA seal and logo shall not be used in any manner to imply endorsement of any commercial product or activity by EPA or the United States Government.
12-
7+
[![Build and Unit Testing](https://github.com/USEPA/Stormwater-Management-Model/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/USEPA/Stormwater-Management-Model/actions/workflows/build-and-test.yml)
8+
[![Build and Regression Testing](https://github.com/USEPA/Stormwater-Management-Model/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/USEPA/Stormwater-Management-Model/actions/workflows/build-and-test.yml)
9+
[![Deployment](https://github.com/USEPA/Stormwater-Management-Model/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/USEPA/Stormwater-Management-Model/actions/workflows/build-and-test.yml)
10+
[![Documentation](https://github.com/USEPA/Stormwater-Management-Model/actions/workflows/build-and-test.yml/badge.svg?branch=docs)](https://github.com/USEPA/Stormwater-Management-Model/actions/workflows/build-and-test.yml)
11+
[![PythonVersion](https://img.shields.io/pypi/pyversions/epaswmm.svg)](https://pypi.org/project/epaswmm)
12+
[![PyPi](https://img.shields.io/pypi/v/epaswmm.svg)](https://pypi.org/project/epaswmm)
1313

1414
## Introduction
1515
This is the official SWMM source code repository maintained by US EPA Office of Research and Development, Center For Environmental Solutions & Emergency Response, Water Infrastructure Division located in Cincinnati, Ohio.
1616

1717
SWMM is a dynamic hydrology-hydraulic water quality simulation model. It is used for single event or long-term (continuous) simulation of runoff quantity and quality from primarily urban areas. SWMM source code is written in the C Programming Language and released in the Public Domain.
1818

19+
## Build Instructions
20+
21+
The 'src' folder of this repository contains the C source code for
22+
version of Storm Water Management Model's computational
23+
engine. Consult the included 'Roadmap.txt' file for an overview of
24+
the various code modules. The code can be compiled into both a shared
25+
object library and a command line executable. Under Windows, the
26+
library file (swmm5.dll) is used to power SWMM's graphical user
27+
interface.
28+
29+
Also included is a python interface for the SWMM computational engine and output
30+
post-processing application programming interfaces located in the python folder.
31+
32+
The 'CMakeLists.txt' file is a script used by CMake (https://cmake.org/)
33+
to build the SWMM binaries. CMake is a cross-platform build tool
34+
that generates platform native build systems for many compilers. To
35+
check if the required version is installed on your system, enter from
36+
a console window and check that the version is 3.5 or higher.
37+
38+
```bash
39+
cmake --version
40+
```
41+
42+
To build the SWMM engine library and its command line executable
43+
using CMake and the Microsoft Visual Studio C compiler on Windows:
44+
45+
1. Open a console window and navigate to the directory where this
46+
Readme file resides (which should have 'src' as a sub-directory
47+
underneath it).
48+
49+
2. Issue the following commands:
50+
51+
```bash
52+
mkdir build
53+
cd build
54+
```
55+
56+
3. Then enter the following CMake commands:
57+
58+
``` bash
59+
cmake -G <compiler> .. -A <platform>
60+
cmake --build . --config Release
61+
```
62+
63+
where `<compiler>` is the name of the Visual Studio compiler being used
64+
in double quotes (e.g., "Visual Studio 15 2017", "Visual Studio 16 2019",
65+
or "Visual Studio 17 2022") and `<platform>` is Win32 for a 32-bit build
66+
or x64 for a 64-bit build. The resulting engine DLL (swmm5.dll), command
67+
line executable (runswmm.exe), and output processing libraries (swmm-output.dll)
68+
will appear in the build\Release directory.
69+
70+
For other platforms, such as Linux or MacOS, Step 3 can be replaced with:
71+
72+
```bash
73+
cmake ..
74+
cmake --build .
75+
```
76+
77+
The resulting shared object library (libswmm5.so or libswmm5.dylib) and
78+
command line executable (runswmm) will appear in the build directory.
79+
80+
The exprimental python bindings can be built and installed locally using the following command.
81+
82+
```bash
83+
cd python
84+
python -m pip install -r requirements.txt
85+
python -m pip install .
86+
```
87+
Users may also build python wheels for installation or distribution. Once the python bindings
88+
have been validated and cleared through EPA'S clearance process, they will be available for installation
89+
via ropsitories such as pypi.
90+
91+
## Unit and Regression Testing
92+
93+
Unit tests and regression tests have been developed for both the natively compiled SWMM computational engine and output toolkit as
94+
well as their respective python bindings. Unit tests for the natively compiled toolkits use the Boost 1.67.0 library and can be
95+
compiled by adding DBUILD_TESTS=ON flag during the cmake build phase as shown below:
96+
97+
```bash
98+
ctest --test-dir . -DBUILD_TESTS=ON --config Debug --output-on-failure
99+
```
100+
101+
Unit testing on the python bindings may be executed using the following command after installation.
102+
103+
```bash
104+
cd python\tests
105+
pytest .
106+
```
107+
108+
Regression tests are executed using the python bindings using the pytest and pytest-regressions extension using the following commands.
109+
110+
```bash
111+
cd ci
112+
pytest --data-dir <path-to-regression-testing-files> --atol <absolute-tolerance> --rtol <relative-tolerance> --benchmark-compare --benchmark-json=PATH
113+
```
114+
19115
## Find Out More
20-
The source code distributed here is identical to the code found at the official [SWMM Website](https://www.epa.gov/water-research/storm-water-management-model-swmm).
116+
The source code distributed here is identical to the code found at the official [SWMM website](https://www.epa.gov/water-research/storm-water-management-model-swmm).
117+
The SWMM website also hosts the official manuals and installation binaries for the SWMM software.
118+
119+
A live web version of the SWMM documentation of the API and user manuals can be found on the [SWMM GitHub Pages website](https://usepa.github.io/Stormwater-Management-Model). Note that this is an alpha version that is still under development and has yet to go through EPA'S official QAQC review process.
120+
121+
## Disclaimer
122+
The United States Environmental Protection Agency (EPA) GitHub project code is provided on an "as is" basis and the user assumes responsibility for its use. EPA has relinquished control of the information and no longer has responsibility to protect the integrity, confidentiality, or availability of the information. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by EPA. The EPA seal and logo shall not be used in any manner to imply endorsement of any commercial product or activity by EPA or the United States Government.
123+

‎Readme.txt

-47
This file was deleted.

‎ci/conftest.py

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# conftest.py
2+
import pytest
3+
import os
4+
5+
def pytest_addoption(parser):
6+
parser.addoption(
7+
"--data-dir", action="store", default=None, help="Directory to search for data files", required=True
8+
)
9+
10+
parser.addoption(
11+
"--atol", action="store", default=None, help="Absolute tolerance for floating point comparisons"
12+
)
13+
14+
parser.addoption(
15+
"--rtol", action="store", default=1.0e-8, help="Relative tolerance for floating point comparisons"
16+
)
17+
18+
parser.addoption(
19+
"--force-regen", action="store_true", default=1.0e-8, help="Force regeneration of the data files"
20+
)
21+
22+
@pytest.fixture
23+
def data_dir(request):
24+
"""
25+
Fixture to get the data directory
26+
"""
27+
return request.config.getoption("--data_dir")
28+
29+
@pytest.fixture
30+
def atol(request):
31+
"""
32+
Fixture to get the absolute tolerance
33+
"""
34+
return request.config.getoption("--atol")
35+
36+
@pytest.fixture
37+
def rtol(request):
38+
"""
39+
Fixture to get the relative tolerance
40+
"""
41+
return request.config.getoption("--rtol")
42+
43+
@pytest.fixture
44+
def force_regen(request):
45+
"""
46+
Fixture to get the force-regen flag
47+
"""
48+
return request.config.getoption("--force_regen")
49+
50+
@pytest.fixture
51+
def discovered_files(data_dir):
52+
"""
53+
Walk through data directory and discover all SWMM input files
54+
"""
55+
if data_dir is None:
56+
return []
57+
return [os.path.join(data_dir, f) for f in os.listdir(data_dir) if os.path.isfile(os.path.join(data_dir, f))]
58+
59+
def pytest_collection_modifyitems(items):
60+
for item in items:
61+
if item.originalname == 'test_compare_node_results' and 'input_file' in item.fixturenames:
62+
input_file = item.callspec.params['input_file']
63+
item._nodeid = f'{item.nodeid}_{os.path.basename(input_file)}'

‎ci/download_benchmarks.py

Whitespace-only changes.

‎ci/requirements.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pytest-regressions

‎ci/test_compare_outputs.py

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import pytest
2+
from epaswmm.output import Output
3+
4+
@pytest.mark.parametrize('input_file', discovered_files)
5+
@pytest.mark.benchmark(group='compare_node_results')
6+
def test_compare_node_results_(benchmark, data_regression, input_file):
7+
"""
8+
Compare the results of the node results and benchmark the execution time.
9+
"""
10+
@benchmark
11+
def run_test():
12+
# Your test logic here
13+
assert True
14+
15+
# Optionally, you can add assertions to check the benchmark results
16+
assert benchmark.stats.mean < 0.1 # Example assertion

0 commit comments

Comments
 (0)
Please sign in to comment.