[1pts] PR: synthetic rating curve calibration with USGS rating and up/down tracing

[RyanSpies-NOAA]

This enhancement includes changes to the SRC calibration routine that uses the USGS published rating curve database. The modifications attempt to mimic the technique used in the stage-based CatFIM where the USGS WSE/flow is propagated upstream and downstream of the gauge location. This closes #892

Additions

src/src_adjust_usgs_rating_trace.py: updated SRC calibration routine to include the a new upstream/downstream tracing routine. The WSE(HAND stage) and flow targets obtained from the USGS rating curve are now applied to all hydroids within 8km (~5 miles) of the gauge location.

Changes

fim_post_processing.sh: using the new src_adjust_usgs_rating_trace.py in place of the src_adjust_usgs_rating.py
src/src_roughness_optimization.py: minor changes to facilitate new calibration input (reset index)
src/utils/shared_variables.py: added USGS_CALB_TRACE_DIST as the trace distance variable

Removals

src/src_adjust_usgs_rating.py: deprecated (replaced with the new src_adjust_usgs_rating_trace.py)

Testing

Completed multiple tests for the UAT and Alpha Test HUC domain (239 hucs)

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
• Passes all unit tests locally (inside interactive Docker container, at /foss_fim/, run: pytest unit_tests/)
• 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
• Reviewers requested
• 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

Notes

Trace example for one gauge location (branch 0)

Example of calibration coefficient results for one huc (branch 0)

Alpha test metrics for AHPS library locations showing comparison between new calibration metrics and "no calibration" results.

[AliForghani-NOAA]

I successfully tested this PR (after merging the latest dev into its branch) for HUC 12040101. For this test, I set below in the param.env file: src_adjust_ras2fim="False" and src_adjust_spatial="False"

Plots below compare Alpha test results between latest dev, and latest dev with this PR changes. We see an BLE skill increase as below:

In NWS AHPS evaluations, no impact is noticed simply due to the USGS gauges being located far away from the benchmark grid's extent.

[RobHanna-NOAA]

Updated change log which was having merge issues with dev