RTX Code Release (PI-4): T-Route Integration Test additions

LICENSE

@@ -1,7 +1,57 @@
-“Software code created by U.S. Government employees is not subject to copyright
+This project contains both software components and data components, each under their respective licenses:
+
+SOFTWARE LICENSE
+-----------------
+
+Copyright 2024 Raytheon Company
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation 
+and/or other materials provided with the distribution.
+
+Licensed under: https://opensource.org/license/bsd-2-clause
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+All rights reserved. Based on Government sponsored work under contract GS-35F-204GA.
+
+-----------------
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-----------------
+
+"Software code created by U.S. Government employees is not subject to copyright
 in the United States (17 U.S.C. §105). The United States/Department of Commerce
 reserve all rights to seek and obtain copyright protection in countries other
 than the United States for Software authored in its entirety by the Department
 of Commerce. To this end, the Department of Commerce hereby grants to Recipient
 a royalty-free, nonexclusive license to use, copy, and create derivative works
-of the Software outside of the United States.”
+of the Software outside of the United States."
+
+DATA LICENSE
+-----------------
+
+Geospatial data files contained within this repository were derrived from the Cloud Native Water Resource Modeling Hydrofabric dataset and are made available under the Open Database License (ODbL).
+
+You are free to use, copy, distribute, transmit and adapt our data, as long as you credit Raytheon and its contributors.
+
+Citation:
+Johnson, J. M. (2022). National Hydrologic Geospatial Fabric (hydrofabric) for the Next Generation (NextGen) Hydrologic Modeling Framework,
+HydroShare http://www.hydroshare.org/resource/129787b468aa4d55ace7b124ed27dbde
+
+Any rights in individual contents of the dataset are licensed under the Database Contents License.
+
+For the complete ODbL license text, visit: http://opendatacommons.org/licenses/odbl/1.0/
+For the complete Database Contents License, visit: http://opendatacommons.org/licenses/dbcl/1.0/s

doc/docker/dockerfile_notebook.md

@@ -0,0 +1,38 @@
+# Dockerfile.Notebook
+
+This document describes the Docker setup for running JupyterLab with mounted volumes for development and analysis.
+
+## Container Overview
+
+The container provides a JupyterLab environment with:
+- Python environment for data analysis
+- Web interface accessible via port 8000
+
+This container is a great way to run examples and integrated tests
+
+## Docker Configuration
+
+### Dockerfile
+The Dockerfile sets up:
+- Base Python environment
+- JupyterLab installation
+- Volume mount points for data and code
+- Port 8000 exposed for web interface
+- Working directory configuration
+
+### Getting Started
+
+Build:
+```bash
+docker build -t troute-notebook -f docker/Dockerfile.notebook .
+```
+
+Run:
+```bash
+docker run -p 8000:8000 troute-notebook
+```
+
+Then, take the URL from the output and put that into your browser. An example one is below:
+```
+http://127.0.0.1:8000/lab?token=<token>
+```

docker/Dockerfile.notebook

@@ -0,0 +1,29 @@
+FROM rockylinux:9.2 as rocky-base
+RUN yum install -y epel-release 
+RUN yum install -y netcdf netcdf-fortran netcdf-fortran-devel netcdf-openmpi
+
+RUN yum install -y git cmake python python-devel pip 
+
+WORKDIR "/t-route/"
+
+COPY . /t-route/
+
+RUN ln -s /usr/lib64/gfortran/modules/netcdf.mod /usr/include/openmpi-x86_64/netcdf.mod
+
+ENV VIRTUAL_ENV=/opt/venv
+RUN python3 -m venv $VIRTUAL_ENV
+
+# Equivalent to source /opt/venv/bin/activate
+ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+
+RUN python -m pip install .
+RUN python -m pip install .[jupyter]
+RUN python -m pip install .[test]
+
+RUN ./compiler.sh no-e
+
+EXPOSE 8000
+
+# increase max open files soft limit
+RUN ulimit -n 10000
+CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8000", "--no-browser", "--allow-root"]

pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "troute_project"
+authors = [
+    {name = "DongHa Kim", email = "[email protected]"},
+    {name = "Sean Horvath", email = "[email protected]"},
+    {name = "Amin Torabi", email = "[email protected]"},
+    {name = "Zach Jurgen", email = "[email protected]"},
+    {name = "Austin Raney", email = "[email protected]"},
+]
+dynamic = ["version", "dependencies"]
+
+[tool.setuptools.dynamic]
+dependencies = {file = ["requirements.txt"]}
+
+[project.optional-dependencies]
+test = [
+    "pytest==8.3.2",
+    "bmipy==2.0.0",
+]
+
+jupyter = [
+    "contextily==1.6.0",
+    "matplotlib>=3.7.0,<3.8.0",  # More stable version range
+    "ipykernel>=6.29.0,<7.0.0",
+    "jupyterlab>=3.6.7,<4.0.0",
+    "xarray>=2024.1.1",
+    "matplotlib-inline>=0.1.6"  # Add explicit version
+]

test/README.md

@@ -0,0 +1,70 @@
+# Test Directory Structure
+
+This directory is meant for the following purposes:
+- Integration testing of individual functions/class objects within T-Route
+- Hosting example data to run full-length test runs
+
+## Quick Start
+
+```bash
+# Run all tests
+pytest test/
+
+# Run tests from a specific category
+pytest test/troute-config/
+pytest test/troute-network/
+pytest test/troute-nwm/
+pytest test/troute-bmi/
+```
+
+## Test Categories
+
+### Config Tests (`test/troute-config/`)
+
+**Usage:**
+- Validating existing Troute example configs
+- Testing the Pydantic Config Validations
+
+### Network Tests (`test/troute-network/`)
+
+**Usage:**
+- Using YAML files from `NHD` and `HYFeatures` in order to test network creation
+
+### NWM Tests (`test/troute-nwm/`)
+
+**Usage:**
+- end to end tests of individual functions within the following functions:
+  - `main_v03()`
+  - `main_v04()`
+
+### BMI Tests (`test/troute-bmi/`)
+
+**Usage:**
+- Integration tests for the BMI NWM implementation of T-Route
+
+### End to End Examples:
+##### `test/LowerColorado_TX/`
+##### `test/LowerColorado_TX_v4/`
+##### `test/unit_test_hyfeature/`
+
+## Best Practices
+
+1. Always use the appropriate fixture for your test case to minimize setup code
+2. Use `temporarily_change_dir` context manager when working with paths to ensure you're able to run integration tests successfully
+3. Check fixture contents before using them in tests
+4. Use fixture combinations when testing complex interactions
+
+## Adding New Fixtures
+
+When adding new fixtures:
+1. Follow the existing naming convention
+2. Document the fixture structure and purpose
+3. Include example usage
+4. Add any necessary dependencies
+5. Update this README with new end to end test docs or examples
+
+## Adding New Tests
+
+1. Create new test files in the appropriate category directory
+2. Use the naming convention `test_*.py` for test files
+3. Document any new fixtures in the relevant conftest.py

test/__init__.py

@@ -0,0 +1,41 @@
+import os
+from contextlib import contextmanager
+from pathlib import Path
+
+
+@contextmanager
+def temporarily_change_dir(path: Path):
+    """Temporarily changes the current working directory
+
+    This context manager changes the current working directory to the specified path,
+    yields control back to the caller, and then changes back to the original directory
+    when exiting the context
+
+    Parameters
+    ----------
+    path : Path
+        The path to temporarily change the current working directory to
+
+    Yields
+    ------
+    None
+    """
+    original_cwd = Path.cwd()
+    if original_cwd != path:
+        os.chdir(path)
+    try:
+        yield
+    finally:
+        if original_cwd != path:
+            os.chdir(original_cwd)
+
+
+def find_cwd(path=None) -> Path:
+    if path is not None:
+        cwd = path
+    else:
+        cwd = Path.cwd()
+    if "test" in str(cwd):
+        while "test" in str(cwd):
+            cwd = cwd.parent
+    return cwd