NGWPC PI-6 Delivery: Replace and Route

.gitignore

@@ -79,3 +79,5 @@ bower_components/
 .grunt/
 src/vendor/
 dist/
+
+build/

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+        files: ^src/troute-rnr/
+      - id: end-of-file-fixer
+        files: ^src/troute-rnr/
+      - id: check-yaml
+        files: ^src/troute-rnr/
+      - id: debug-statements
+        files: ^src/troute-rnr/
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.5
+    hooks:
+      - id: ruff
+        args: ["--fix", "--config=src/troute-rnr/pyproject.toml"]
+        files: ^src/troute-rnr/
+      - id: ruff-format
+        files: ^src/troute-rnr/

LICENSE

@@ -1,3 +1,22 @@
+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.
+
+-----------------
 
                                  Apache License
                            Version 2.0, January 2004
@@ -200,3 +219,29 @@
    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."
+
+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

compiler_uv.sh

@@ -0,0 +1,128 @@
+#TODO add options for clean/noclean, make/nomake, cython/nocython
+#TODO include instuctions on blowing away entire package for fresh install e.g. rm -r ~/venvs/mesh/lib/python3.6/site-packages/troute/*
+#set root folder of github repo (should be named t-route)
+REPOROOT=`pwd`
+#For each build step, you can set these to true to make it build
+#or set it to anything else (or unset) to skip that step
+build_mc_kernel=true
+build_diffusive_tulane_kernel=true
+build_reservoir_kernel=true
+build_framework=true
+build_routing=true
+build_config=true
+build_nwm=true
+
+if [ -z "$F90" ]
+then
+    export F90="gfortran"
+    echo "using F90=${F90}"
+fi
+if [ -z "$CC" ]
+then
+    export CC="gcc"
+    echo "using CC=${CC}"
+fi
+
+#preserve old/default behavior of installing packages with -e
+WITH_EDITABLE=true
+if [ "$1" == 'no-e' ]
+then
+WITH_EDITABLE=false
+fi
+
+#if you have custom static library paths, uncomment below and export them
+#export LIBRARY_PATH=<paths>:$LIBRARY_PATH
+#if you have custom dynamic library paths, uncomment below and export them
+#export LD_LIBRARY_PATHS=<paths>:$LD_LIBRARY_PATHS
+if [ -z "$NETCDF" ]
+then
+    export NETCDFINC=/usr/include/openmpi-x86_64/
+    # set alternative NETCDF variable include path, for example for WSL
+    # (Windows Subsystems for Linux).
+    #
+    # EXAMPLE USAGE: export NETCDFALTERNATIVE=$HOME/.conda/envs/py39/include/
+    # (before ./compiler.sh)
+    if [ -n "$NETCDFALTERNATIVE" ]
+    then
+	echo "using alternative NETCDF inc ${NETCDFALTERNATIVE}"
+	export NETCDFINC=$NETCDFALTERNATIVE
+    fi
+else
+    export NETCDFINC="${NETCDF}"
+fi
+echo "using NETCDFINC=${NETCDFINC}"
+
+if  [[ "$build_mc_kernel" == true ]]; then
+  #building reach and resevoir kernel files .o
+  cd $REPOROOT/src/kernel/muskingum/
+  make clean
+  make  || exit
+  make install || exit
+fi
+
+if  [[ "$build_diffusive_tulane_kernel" == true ]]; then
+  #building reach and resevoir kernel files .o  
+  cd $REPOROOT/src/kernel/diffusive/
+  make clean
+  make diffusive.o
+  make pydiffusive.o
+  make chxsec_lookuptable.o
+  make pychxsec_lookuptable.o
+  make install || exit
+fi
+
+if [[ "$build_reservoir_kernel" == true ]]; then
+  cd $REPOROOT/src/kernel/reservoir/
+  make clean
+  #make NETCDFINC=`nc-config --includedir` || exit
+  #make binding_lp.a
+  #make install_lp || exit
+  make
+  make install_lp || exit
+  make install_rfc || exit
+
+fi
+
+if [[ "$build_framework" == true ]]; then
+  #creates troute package
+  cd $REPOROOT/src/troute-network
+  rm -rf build
+
+  if [[ ${WITH_EDITABLE} == true ]]; then
+    uv pip install --no-build-isolation --config-setting='--build-option=--use-cython' --editable . --config-setting='editable_mode=compat' || exit
+  else
+    uv pip install --no-build-isolation --config-setting='--build-option=--use-cython' . || exit
+  fi
+fi
+
+if [[ "$build_routing" == true ]]; then
+  #updates troute package with the execution script
+  cd $REPOROOT/src/troute-routing
+  rm -rf build
+
+  if [[ ${WITH_EDITABLE} == true ]]; then
+    uv pip install --no-build-isolation --config-setting='--build-option=--use-cython' --editable . --config-setting='editable_mode=compat' || exit
+  else
+    uv pip install --no-build-isolation --config-setting='--build-option=--use-cython' . || exit
+  fi
+fi
+
+if [[ "$build_config" == true ]]; then
+  #updates troute package with the execution script
+  cd $REPOROOT/src/troute-config
+  if [[ ${WITH_EDITABLE} == true ]]; then
+    uv pip install --editable . || exit
+  else
+    uv pip install . || exit
+  fi
+fi
+
+if [[ "$build_nwm" == true ]]; then
+  #updates troute package with the execution script
+  cd $REPOROOT/src/troute-nwm
+  if [[ ${WITH_EDITABLE} == true ]]; then
+    uv pip install --editable . || exit
+  else
+    uv pip install . || exit
+  fi
+fi

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 = "dongha.kim@noaa.gov"},
+    {name = "Sean Horvath", email = "sean.horvath@noaa.gov"},
+    {name = "Amin Torabi", email = "amin.torabi@noaa.gov"},
+    {name = "Zach Jurgen", email = "jurgen.zach@noaa.gov"},
+    {name = "Austin Raney", email = "austin.raney@noaa.gov"},
+]
+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",
+    "ipykernel>=6.29.0,<7.0.0",
+    "jupyterlab>=3.6.7,<4.0.0",
+    "xarray>=2024.1.1",
+    "matplotlib-inline>=0.1.6"
+]

src/troute-config/pyproject.toml

@@ -1,6 +1,6 @@
 [build-system]
 build-backend = "setuptools.build_meta"
-requires = ["setuptools", "setuptools-scm"]
+requires = ["setuptools"]
 
 [project]
 authors = [
@@ -19,7 +19,7 @@ classifiers = [
   "Topic :: Utilities",
 ]
 dependencies = [
-  "pydantic~=1.10",
+  "pydantic==2.11.4",
   "typing_extensions",
 ]
 description = "Modules for validating and programatically accessing troute configuration files."

src/troute-config/test/__init__.py

@@ -0,0 +1,31 @@
+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)

src/troute-config/test/conftest.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+import pytest
+import yaml
+from _pytest.fixtures import FixtureRequest
+
+
+def find_config_files() -> List[Path]:
+    """Finds all `.yaml` configuration files within specified directories
+
+    Returns
+    -------
+    List[Path]
+        A list of Path objects pointing to each valid configuration
+    """
+    test_dir = Path(__file__).parents[3] / "test"  # Searching for the t-route/test dir
+    target_dirs = ["LowerColorado_TX", "LowerColorado_TX_v4", "LowerColorado_TX_HYFeatures_v22", "unit_test_hyfeature"]
+    files = []
+    for dir_name in target_dirs:
+        files.extend(list((test_dir / dir_name).glob("*.yaml")))
+    return files
+
+
+@pytest.fixture(params=find_config_files())
+def config_data(request: FixtureRequest) -> Tuple[Path, Dict[str, Any]]:
+    """A fixture for loading yaml files into python dictionary mappings
+
+    Parameters
+    ----------
+    request : FixtureRequest
+        The pytest request object, containing the current parameter value
+
+    Returns
+    -------
+    Tuple[Path, Dict[str, Any]]
+        A tuple containing the path to the YAML file and the loaded data as a dictionary
+    """
+    data = yaml.load(request.param.read_text(), Loader=yaml.Loader)
+    return request.param, data