NGWPC NWM PI-3 Formulation Selection Delivery 2026-02-25

[cmaynard-ngwpc]

This pull request delivers substantial usability, correctness, and scalability improvements to nwm-region-mgr, with a strong emphasis on regionalization robustness, documentation clarity, domain awareness (including oCONUS and Alaska), and workflow operability.

The PR enhances support for formulation and parameter regionalization, improves memory efficiency for large spatial computations, strengthens configuration validation, and modernizes documentation and Docker-based deployment. It also removes obsolete code and scripts, simplifying long-term maintenance.

---

Additions

Regionalization & Algorithms

• Added support for using a proximity-based regionalization algorithm.
• Added improved support for formulation selection in Alaska.
• Added safeguards when no donors are available in a snow group.
• Added spatial maps of regionalized parameters and plotting support.
• Added a utility script to generate ngen ↔ HUC12 crosswalks for all domains.
• Added help text for workflow options and clearer validation of regionalization modes.
• Added a configurable parameter to explicitly control NWM routing fallback (use_nwm_routing_fallback).

Documentation & User Guidance

• Added a full User’s Guide and expanded FAQ content (including attributes and snowiness).
• Added links to Confluence verification documentation.
• Added documentation for local regionalization runs.
• Added spatial parameter map examples to the docs.
• Added comments and guidance for oCONUS domains.

Deployment & Tooling

• Added Docker support for:

  • Region workflows
  • NGEN
  • Evaluation
  • Routing (region_rte, ngen_rte)

• Added cleaned and consolidated example configs to facilitate end-to-end testing.

---

Changes

Correctness & Robustness

• Fixed bugs in:
  • Donor selection logic
  • select_formulation_donors_only
  • Handling buffer_size=0 with calib_basins_only=True
  • Output file path resolution
  • VPU GeoDataFrame handling for plotting
• Changed certain hard errors to warnings to prevent unnecessary workflow termination.
• Ensured vpu_list consistency with configured domains.
• Improved StreamCat attribute computation logic.
• Improved timestamp handling by enforcing global timestamp formats.

Performance & Scalability

• Improved memory efficiency of distance-matrix calculations for URF.
• Refactored subset scripts and configuration expansion logic for efficiency.
• Updated defaults (e.g., nprocs = -1) to better utilize available resources.

Configuration & Workflow Behavior

• Updated regionalization workflow to run both parameter and formulation regionalization.
• Refactored expand_config_for_vpu.
• Fixed argument options and function naming inconsistencies.
• Updated config files for ngen, eval, and regional workflows.
• Adjusted output subdirectory layouts for consistency.
• Cleaned up and standardized README and documentation text.
• Consolidated and cleaned configuration examples.

---

Removals

• Removed obsolete scripts and utilities:
  • Legacy shell scripts (region-mgr.sh)
  • Deprecated workflow scripts (run_formreg.py)
  • Unused utility files (utils/cfu)
• Removed unused or obsolete plotting code.
• Removed old sample file references and deleted the legacy sample_files directory.
• Removed deprecated subset scripts that were superseded by more efficient logic.
• Removed unused imports and dead code paths.
• Disabled legacy implicit NWM routing fallback behavior and replaced it with an explicit config option.