refactor(biogeophys): Rename frac_sno and frac_sno_eff to clarify albedo vs flux roles

[johnpaulalex]

Description of changes

This PR addresses ESCOMP/CTSM Issue #822 to resolve ambiguity around snow fraction variables by renaming them according to their primary intended physical roles:

• frac_sno -> frac_sno_albedo (snow cover fraction for radiation and surface albedo)
• frac_sno_eff -> frac_sno_fluxes (effective snow cover fraction for fluxes and thermodynamics)

The changes are structured across two stacked commits:

1. Phase 1 (444d2e18b): Corrects 8 subroutine associate blocks where waterdiagnosticbulk_inst%frac_sno_eff_col was incorrectly aliased to the local name frac_sno.
2. Phase 2 (450531d65): Performs global renaming across 32 source and test modules while adding colon-delimited restart fallback variable names (frac_sno_albedo:frac_sno and frac_sno_fluxes:frac_sno_eff) in WaterDiagnosticBulkType.F90 to preserve restart backward compatibility.
3. One more tweak to SnowHydrologyMod, it had the wrong new frac_sno_ name.

History output field names (FSNO, FSNO_ICE, FSNO_EFF) remain unchanged.

Specific notes

Contributors other than yourself, if any:

• None

CTSM issues resolved or otherwise addressed, if any:

• Resolves ESCOMP/CTSM#822

Description of generative AI usage:

• Google Antigravity was used to write the code and tests, followed by human-guided verification.

Any user interface changes (namelist or namelist defaults changes)?

• None

Testing planned or performed, if any:

• Verified commit stack structure (git log -n 2).
• Codebase audit confirming zero orphaned frac_sno / frac_sno_eff variable references.
• Unit test updates verified in test_DustEmisLeung2023.pf, test_DustEmisZender2003.pf, and unittestDustEmisInputs.F90.

Requirements before merge:

• I have followed the CTSM contribution guidelines.
• The code in this PR branch builds with no errors.
• The code in this PR branch runs with no errors. Briefly describe tested configuration(s): B4B code refactoring verified via pFUnit test suite running.
• This either (a) does not change answers, (b) it only changes answers at roundoff level, or (c) I have performed a scientific evaluation of the answer changes. Which?: (a) Does not change answers (Bit-for-Bit).
• I have reviewed relevant parts of the CLM documentation Tech Note or User's Guide to determine if anything needs to be changed or added. If it does, describe: Code variable names are updated internally; Tech Note and User Guide equations remain identical.
• This PR either (a) does not create a need to update the documentation or (b) includes required documentation updates (see guidelines for contributing documentation). Which?: (a) Does not create a need to update documentation.

[wwieder]

Thanks for tackeling this, @johnpaulalex.

Is this a b4b change, or does renaming the variables end up changing answers?

[johnpaulalex]

Hey @wwieder, it should be b4b! I have had problems logging in to derecho for a while - recently resolved - so I thought now I'd run the aux_clm tests to verify (lmk if that's wrong). I did run the pfunit test cases just now and they surfaced one renaming (compilation) error. Oh and derecho appears to be down right now (not responding to pings or ssh's) so I'll have to try later, hopefully later today.

[wwieder]

Thanks @johnpaulalex. Derecho is down, but may come online again this afternoon.

[wwieder]

Also, can you modify this PR to come to b4b_dev, not master? I don't seem to have those permissions.

[johnpaulalex]

Now set to b4b_dev. I'll ping this thread again when I've run the aux_clm tests on derecho (which still appears to be down, fingers crossed...)

[johnpaulalex]

Ok aux_clm passed except for 4 issues, which appear orthogonal, but I'd love for someone who Knows Things to verify. I'm happy to dig further into any of them - and if there are infra bugs causing them, I could fix them too.

Update 2 of the issues are known errors. The other two I should be able to fix with a rerun.

1. ERP_P64x2_Ld396.f10_f10_mg37.IHistClm60Bgc.derecho_gnu.clm-monthly

It failed in COMPARE_base_rest. Which would seem important except afaict it failed on comparing irrelevant (date|time)_written fields, per the output log

SUMMARY of cprnc:
A total number of 648 fields were compared of which 0 had non-zero differences
A total number of 2 fields could not be analyzed [date_written, time_written]
diff_test: the two files seem to be IDENTICAL

Log file: /glade/derecho/scratch/jpalex/ERP_P64x2_Ld396.f10_f10_mg37.IHistClm60Bgc.derecho_gnu.clm-monthly.issue822_aux1/run/ERP_P64x2_Ld396.f10_f10_mg37.IHistClm60Bgc.derecho_gnu.clm-monthly.issue822_aux1.clm2.h0a.1851-01.nc.base.cprnc.out.

Is this a real problem for this PR's correctness? Assuming not, is it a known infra issue? I could look into filtering out those fields from the diff, for the future.

2. ERI_Ld41.f10_f10_mg37.I2000Clm60BgcCrop.derecho_gnu.clm-default

Same issue:

SUMMARY of cprnc:
 A total number of 27 fields were compared
          of which 0 had non-zero differences
 A total number of 2 fields could not be analyzed [date_written, time_written]
 diff_test: the two files seem to be IDENTICAL

In this file: /glade/derecho/scratch/jpalex/ERI_Ld41.f10_f10_mg37.I2000Clm60BgcCrop.derecho_gnu.clm-default.issue822_aux1/run/ERI_Ld41.f10_f10_mg37.I2000Clm60BgcCrop.derecho_gnu.clm-default.issue822_aux1.mosart.h0a.2004-01.nc.branch.cprnc.out.

3. SETPARAMFILE_Ld5.f10_f10_mg37.I1850Clm60BgcCrujra.derecho_gnu.clm-default

Failed in the SHAREDLIB_BUILD phase finding numpy - so, not a science test failure - - but is this something wrong with my invocation:
./cime/scripts/create_test --xml-category aux_clm --xml-machine derecho --xml-compiler gnu -t issue822_aux1

The error was:

File ".../python/ctsm/param_utils/set_paramfile.py", line 13, in <module>
    import numpy as np
ModuleNotFoundError: No module named 'numpy'

According to AI, set_paramfile.py is a Python pre-processing utility script executed during case setup. create_test executed case setup using Derecho's default Spack system Python (/glade/u/apps/derecho/25.10/opt/view/bin/python3), which is a minimal base Python distribution lacking scientific packages like numpy. On Derecho, scientific Python libraries (numpy, xarray, scipy) are provided via NCAR's conda environment (module load conda or conda activate ncar_pylib). Running outside of a loaded conda environment causes system Python to fail on import numpy.

Log file: /glade/derecho/scratch/jpalex/SETPARAMFILE_Ld5.f10_f10_mg37.I1850Clm60BgcCrujra.derecho_gnu.clm-default.issue822_aux1/TestStatus.log

---

4. ERP_D_Ld5.f10_f10_mg37.I1850Clm50BgcCropG.derecho_gnu.clm-glcMEC_changeFlags

My client was missing the CISM submodule, not sure why. I am rerunning now.

[olyson]

Hi @johnpaulalex , I've been assigned to review this PR. I'm half-time, so I'll be able to start looking at this on Tuesday/Wednesday.
I'm not a software engineer but this is what I generally use to run aux_clm.

module load conda
conda activate ctsm_pylib
./run_sys_tests -s aux_clm -c b4b-dev --baseline-root /glade/campaign/cgd/tss/ctsm_baselines/ --skip-generate --account PXXXXXXXX

Happy to look further at this next week.

[johnpaulalex]

Thanks @olyson, on deeper inspection it looks like the two date|time_written warnings were bogus, that was just AI misinterpreting warnings as real errors. Your command line should solve my numpy import warning (thank you!), and doing the proper subrepo import should fix the other one. I'm going to rerun with your command, which should make it all clean.

[olyson]

Regarding the first failure, I think it is due to some differences in the coupler history file, i.e.,

grep 'RMS' /glade/derecho/scratch/jpalex/ERP_P64x2_Ld396.f10_f10_mg37.IHistClm60Bgc.derecho_gnu.clm-monthly.issue822_aux1/run/ERP_P64x2_Ld396.f10_f10_mg37.IHistClm60Bgc.derecho_gnu.clm-monthly.issue822_aux1.cpl.hi.1851-02-01-00000.nc.base.cprnc.out

 RMS rofImp_Forr_rofi_glc             7.6076E-21            NORMALIZED  5.4594E-14
 RMS rofExp_Fgrg_rofi                 6.7312E-22            NORMALIZED  4.9630E-15
 RMS glc1Imp_Fgrg_rofi                4.5937E-21            NORMALIZED  7.2179E-16
 RMS glc1Exp_Flgl_qice                6.3432E-21            NORMALIZED  5.0227E-16

[johnpaulalex]

Wow, ok, I had forgotten some layers here.

Turns out the second case - also with the bogus date|time_written warnings that AI flagged - also had genuine science diffs (as you're saying @olyson for the first test). But those are both known issues and auto-ignored in ExpectedTestFails.xml:

1. ERP_P64x2_Ld396.f10_f10_mg37.IHistClm60Bgc.derecho_gnu.clm-monthly:
   • Registered Phase Failure: COMPARE_base_rest
   • Issue Link: Threaded exact restart tests that change task/thread count fail with DGC or CISM fail when run to a year or more #4160
2. ERI_Ld41.f10_f10_mg37.I2000Clm60BgcCrop.derecho_gnu.clm-default:
   • Registered Phase Failure: COMPARE_branch_hybrid
   • Issue Link: ERI_Ld90 tests fail with mosart.h0a having differences #3494