change vertical interpolation search algorithm from linear to binary

[HelinWei-NOAA]

DESCRIPTION OF CHANGES:

The current vertical interpolation logic in chgres_cube exhibits a significant performance bottleneck when downscaling (e.g., from 127 to 64 levels). This is due to the RSEARCH subroutine employing a linear search algorithm. In a linear search, the computational cost scales as O(N), requiring up to N comparisons per target point, where N is the number of input vertical levels. Consequently, as the input grid density increases, the execution time for coordinate lookup grows substantially.

This PR replaces the linear scan in RSEARCH with a Binary Search algorithm. Because the vertical coordinate arrays (e.g., Z1) are guaranteed to be monotonic, a binary search reduces the search complexity from O(N) to O(log N). This change ensures that the search time remains nearly constant regardless of vertical resolution—reducing the maximum number of comparisons for a 127-level grid from 127 down to just 7.

Performance: Dramatically reduces execution time for the horizontal and vertical interpolation of atmospheric fields.
Consistency: The numerical results remain bit-for-bit identical, as the logic for finding the surrounding interval is mathematically equivalent.
Scalability: Both upscaling (64 to 127) and downscaling (127 to 64) operations are now significantly more efficient.

TESTING

WHICH CONSISTENCY TESTS TO RUN:

• chgres_cube
• cpld_gridgen
• global_cycle
• grid_gen
• ice_blend
• ocnice_prep
• regrid_sfc
• snow2mdl
• weight_gen

TESTS CONDUCTED:

• Compile branch using Intel:
  • Orion
  • Ursa
  • Hercules
  • WCOSS2
• Compile branch using GNU:
  • Ursa
• Compile branch in 'Debug' mode:
  • WCOSS2
• Compile with Doxygen with no errors.
• Run unit tests on any Tier 1 machine.
• Run relevant consistency tests:
  • Orion (passed: 2b14cad)
  • Ursa (passed: 2b14cad)
  • Hercules (passed: 2b14cad)
  • WCOSS2 (passed: 2b14cad)

Optional test.

• Run full set of chgres_cube consistency tests on Ursa.

Describe any additional tests performed.

DEPENDENCIES:

DOCUMENTATION:

• Doxygen does not need updates.
• Doxygen is updated.

LINKED ISSUES:

CONTRIBUTORS (optional):

[BrianCurtis-NOAA]

Good morning @HelinWei-NOAA I will start working on this PR once you get the chance to update to the latest code from the develop branch.

[HelinWei-NOAA]

@BrianCurtis-NOAA Done. Thanks.

[BrianCurtis-NOAA]

THanks! Could you update https://github.com/HelinWei-NOAA/UFS_UTILS/blob/lin2binsrch/docs/source/chgres_cube.rst with updates related to your changes here?

[HelinWei-NOAA]

@BrianCurtis-NOAA My PR does not change any argument lists or configuration files. It seems there is no need to update the documentation unless I’m missing something.

[BrianCurtis-NOAA]

@BrianCurtis-NOAA My PR does not change any argument lists or configuration files. It seems there is no need to update the documentation unless I’m missing something.

No problem, it mentions vertical interpolation, so I wanted to double check if there was anything else you felt might need to be added here.

Orion/Hercules are down, so i'll be able to finish testing tomorrow.