eCLM-ParFlow: account for soil ice when receiving ParFlow water content (#126, #123)

[s-poll]

Text revised with AI

Problem

Two symptoms in eCLM-ParFlow coupled runs trace back to the same defect:

• eCLM-ParFlow: Corrupted H2OSOI_ICE values on urban columns #126: restart files from coupled spin-ups carry non-physical H2OSOI_ICE
  (1.4e30 – 2.15e34 kg/m²) on all 404 urban columns (ltype=9) of EUR-12. Reusing such
  a restart as initial condition for ICON-eCLM yields ICOSHFLX ~1e35 W/m² and crashes ICON.
• eCLM-ParFlow: Soil moisture disagreements in real case Parflow-coupled runs #123: eCLM soil saturation in ParFlow-coupled runs locally exceeds 100 %,
  up to ~20x nominal, predominantly in winter.

Root Cause

soilwater_parflow (SoilWaterMovementMod.F90) received the ParFlow water content and
assigned it wholesale to the liquid phase:

    h2osoi_liq(c,j) = pfl_h2osoi_liq(c,j)

ParFlow has no ice phase, so pfl_h2osoi_liq is the total soil water of the column.
The ice content diagnosed by PhaseChange earlier in the same time step was left untouched,
so total column water seen by eCLM became pfl_h2osoi_liq + h2osoi_ice. Whenever ice was present (i.e. winter), eCLM saturation was correspondingly overestimated (#123).

With nothing bounding ice against the water actually present in the column, the
liquid/ice split fed back into the next time step's phase change and diverged over the
course of a multi-year spin-up, leaving the out-of-range H2OSOI_ICE that ends up in the
restart file (#126).

Solution

Treat the ParFlow field as the total water content and split it into ice and liquid, instead
of overwriting liquid alone:

    ! ParFlow has no ice phase, so the received water is the total water content.
    ! Keep the ice that PhaseChange diagnosed earlier in the time step.
    h2osoi_ice(c,j) = min(h2osoi_ice(c,j), pfl_h2osoi_liq(c,j))
    h2osoi_liq(c,j) = max(0._r8, pfl_h2osoi_liq(c,j) - h2osoi_ice(c,j))

• The ice content is capped by the water ParFlow reports for that layer, so it can no longer
  grow without bound -> fixes eCLM-ParFlow: Corrupted H2OSOI_ICE values on urban columns #126.
• h2osoi_liq + h2osoi_ice now equals pfl_h2osoi_liq, i.e. eCLM and ParFlow agree on total
  column water -> removes the winter saturation overshoot in eCLM-ParFlow: Soil moisture disagreements in real case Parflow-coupled runs #123.
• Liquid water cannot become negative.
• Behaviour is unchanged where no ice is present, so summer/growing-season results are
  bit-identical to master.
• Only active under COUP_OAS_PFL; standalone eCLM and ICON-eCLM code paths untouched.

Known limitation: water balance closure

The passing of the ParFlow H2OSOI_liq could be done before the phase changes, to better account for water balance. Would require a relocation of the variable passing.

This change makes the two components agree on the total soil water of a column, but it does
not make the coupled system water-conserving, and the eCLM water balance check can still show
a non-zero residual in freezing periods. The soil moisture state remains a one-way exchange:
eCLM receives the total water from ParFlow and partitions it into ice and liquid, but that
partition is never communicated back. ParFlow continues to treat the entire column water as
mobile liquid and transports it accordingly, so the two models re-diverge within the very next
time step. On top of that, the min() cap silently drops ice mass whenever the ice diagnosed by PhaseChange exceeds the water ParFlow reports for that layer (e.g. after ParFlow has drained a layer that eCLM had
frozen); that mass is discarded rather than being routed back into the coupled system, and the
associated latent heat of fusion is not accounted for either.

Closing the balance properly requires either a two-way coupling of the soil moisture state — eCLM returning its liquid/ice partition so that ParFlow updates its own storage consistently or, as a minimum step, passing
the ice fraction to ParFlow so that ParFlow can reduce the available pore space and apply an ice
impedance to hydraulic conductivity instead of moving frozen water.

Related issues

Closes #126
Addresses the winter high-water-content part of #123 (the remaining saturation
disagreement is not covered here; keep #123 open).

[kvrigor]

@s-poll from our discussion yesterday with @kgoergen , you'll have more upcoming eCLM-Parflow fixes. My suggestions about code comments could be done on those PRs.