aircraft & downwelling RT support, surface-reflectance derivation, and clear-sky bookkeeping fixes

[BenjaminTJohnson]

Summary

This PR extends CRTM forward, tangent-linear, adjoint, and K-matrix functionality to support radiative transfer at aircraft pressure levels and user-defined downwelling-radiance pressure levels. It also hardens cloud-fraction handling, improves clear-sky output consistency, integrates optional surface-reflectance derivation across all solution paths, and fixes several scattering and surface-optics edge cases for improved physical and numerical robustness. :contentReference[oaicite:0]{index=0}

Key changes

1. Aircraft-pressure and downwelling-radiance support

• Adds AIRCRAFT_PRESSURE_THRESHOLD and consistent handling of:
  • Opt%Aircraft_Pressure (aircraft RT)
  • Opt%Obs_4_downward_P (downwelling radiance at a pressure level; surface if zero)
• Uses CRTM_Get_PressureLevelIdx to select the closest profile level.
• Issues warnings when the selected profile level differs from the requested pressure by more than the threshold.
• Implemented consistently in FWD, TL, AD, and K-matrix paths.
• Extends ADA TL/AD interfaces to propagate downwelling radiance sensitivities when requested.

2. Clear-sky and fractional-cloud bookkeeping

• Ensures RTV_Clear%n_Stokes follows Opt%n_Stokes overrides.
• Propagates Solar_Flag_true to RTV_Clear for fractionally cloudy atmospheres.
• Explicitly sets Tb_clear and R_clear equal to Brightness_Temperature and Radiance when:
  • Atm%n_Clouds == 0, or
  • total cloud cover < MIN_COVERAGE_THRESHOLD
    (note: this is not aerosol-cleared output).

3. Small cloud-fraction hardening

• When Cloud_Fraction < MIN_COVERAGE_THRESHOLD:
  • Cloud fraction is zeroed.
  • Cloud water content and effective radius are zeroed.
• Prevents numerically tiny cloud fractions from activating cloudy/scattering pathways.

4. Surface reflectance derivation hook

• Integrates ADA_Module::CRTM_SurfRef into FWD/TL/AD/K-matrix solutions.
• Activated when:
  • Options_Present
  • opt%Derive_Surface_Refl == .TRUE.
  • mth_Azi == 0
  • COS_SUN > 0
• Ensures consistent surface-reflectance behavior across all linearizations.

5. Scattering and surface-optics correctness fixes

• Cloud scattering TL: backscattering coefficient updates are now gated by
  Is_Active_Sensor and Include_Scattering.
• K-matrix: ensures SfcOptics_K and SfcOptics_Clear_K track Use_New_MWSSEM consistently with the forward path.
• Enforces SfcOptics / SfcOptics_K n_Stokes consistency after option overrides.
• Improves numerical stability and physical consistency in scattering and surface-optics adjoints.

Rationale

These changes enable aircraft- and profile-level downwelling RT use cases, eliminate ambiguous behavior for near-zero cloud fractions, and make clear-sky outputs explicit and reliable. The surface-reflectance and scattering fixes address long-standing edge cases that affected TL/AD/K-matrix consistency.

Notes

• No changes to default behavior unless the new options are explicitly enabled.
• Warnings are informational and intended to flag coarse vertical grids when using aircraft or downwelling pressure modes.

[BenjaminTJohnson]

Note: this has not yet been tested in UFO / FV3-JEDI. I'll probably increment the version number here aiming for v3.2.0, this will be the first of a few PRs heading toward v3.2.0.

[BenjaminTJohnson]

As of this message, this has been tested using IFX / ICX (2025) in jedi-bundle: fv3-jedi, and UFO, under multiple NUM_OMP_THREADS configurations, all ctests pass (except 1 in fv3-jedi and traditionally failing tests in UFO that are unrelated).
This also normalizes CRTM's behavior of openMP, which is now numerically identical with respect to NUM_OMP_THREAD changes across all tests that we have available.

I think it's ready for review.

edit: also this increments the version number to v3.2.0, but it's not there officially yet -- just getting ready.

[BenjaminTJohnson]

The force pushes were reversions back to when things were working in fv3-jedi, I didn't realize that the subsequent changes broke a few tests. I'll work on smaller incremental changes.

[BenjaminTJohnson]

closing in favor of starting a new, clean PR -- this one got too crufty. :)