[3pt] PR: Manning roughness optimization

[hhs732]

This PR focuses on Manning roughness optimization scripts. In earlier versions of FIM (FIM v5 or earlier), global default values of 0.06 for in-channel (channel_n) and 0.12 for overbank (overbank_n) coefficients have been assigned to the Manning equation to estimate discharge for each stage along a synthetic rating curve (SRC). This PR introduces two Python scripts of /src/manningN_optimization.py and tools/run_test_case_mannN_optz_func.py, for each HUC8 for which we have the benchmark data. Applied benchmark data comprises:

• 100-year flood inundation extends for Base Level Engineering (BLE) sites.
• Action, minor, moderate, and major flood stage extends (where available) for Advanced Hydrologic Prediction Service (AHPS) sites.

The algorithm iteratively updates Manning coefficients to minimize false negatives and false positives in inundated grid cells during each optimization cycle. The objective functions are defined as follows:

OBF_BLE = Minimize (false_negatives_count_100y+false_positives_count_100y)
OBF_AHPS = Minimize (false_negatives_count_action+false_positives_count_action+
false_negatives_count_minor+false_positives_count_minor+
false_negatives_count_moderate+ false_positives_count_moderate+
false_negatives_count_major+false_positives_count_major)

The optimization algorithm is subject to several constraints, including:

• overbank_n>channel_n
• 0.006<channel_n<0.15
• 0.018<overbank_n<0.2

The optimization algorithm employs a differential evolution approach, initialized with a population of 15 pairs of in-channel (channel_n) and overbank (overbank_n) Manning’s roughness coefficients.

Closes #1519

Additions

• /src/manningN_optimization.py: Main script that optimizes Manning’s roughness coefficients for each HUC8.
• /tools/run_test_case_mannN_optz_func.py: Contains required functions for manningN_optimization.py

Testing

This PR has been tested on HUCs in the UAT domain.

Deployment Plan (For developer use)

How does the changes affect the product?

• Code only?
• If applicable, has a deployment plan be created with the deployment person/team?
• Require new or adjusted data inputs? Does it have start, end and duration code (in UTC)?
• If new or updated data sets, has the FIM code been updated and tested with the new/adjusted data (subset is fine, but must be a subset of the new data)?
• Require new pre-clip set?
• Has new or updated python packages?

Issuer Checklist (For developer use)

You may update this checklist before and/or after creating the PR. If you're unsure about any of them, please ask, we're here to help! These items are what we are going to look for before merging your code.

• Informative and human-readable title, using the format: [_pt] PR: <description>
• Links are provided if this PR resolves an issue, or depends on another other PR
• If submitting a PR to the dev branch (the default branch), you have a descriptive Feature Branch name using the format: dev-<description-of-change> (e.g. dev-revise-levee-masking)
• Changes are limited to a single goal (no scope creep)
• The feature branch you're submitting as a PR is up to date (merged) with the latest dev branch
• pre-commit hooks were run locally
• Any change in functionality is tested
• New functions are documented (with a description, list of inputs, and expected output)
• Placeholder code is flagged / future todos are captured in comments
• CHANGELOG updated with template version number, e.g. 4.x.x.x
• Add yourself as an assignee in the PR as well as the FIM Technical Lead

Merge Checklist (For Technical Lead use only)

• Update CHANGELOG with latest version number and merge date
• Update the Citation.cff file to reflect the latest version number in the CHANGELOG
• If applicable, update README with major alterations

[AliForghani-NOAA]

The optimization logic looks good, and I was able to run the code successfully.

I also analyzed the optimization results from four AHPS runs (listed below) to quantify the improvement achieved through optimization.

The plot below shows the loss reduction percentage for the analyzed HUCs, highlighting significant improvements. For example, in HUC 12100303, the loss decreased by 95%, from 86,644 to 4,376.

The loss reduction percentage is calculated using the initial and optimized losses as follows:

$$ \text{Loss Reduction %)} = \left( \frac{\text{Initial Loss} - \text{Optimized Loss}}{\text{Initial Loss}} \right) \times 100 $$

• Initial loss is taken from optz_iteration_metrics_{huc_no}.csv (iteration 0)
• Optimized loss is taken from optz_metrics_{huc_no}.csv

I’ve attached the full results in the CSV file for reference.
loss_reduction_summary.csv

[RileyMcDermott-NOAA]

7/17/25 - Still working on review - not ready for merge yet