Skip to content

eCLM-Parflow: OASIS coupling field test #145

Open

Description

@kvrigor

Soil moisture disagreements between eCLM and Parflow (#123 and #103) puts the eCLM-Parflow coupling logic into question, and to proceed further we must be confident that the coupling is 100% correct. The boxplots below were generated from the results of the idealized eCLM-Parflow test case. Here's a few relevant info about this test:

  • Grid characteristics: 2D rectilinear, 70x70 gridcells, periodic boundary conditions
  • OASIS interpolation algorithm: none; fields are passed 1-to-1 between eCLM and Parflow
  • Simulation duration: 24 timesteps 24 hrs = 145 timesteps
  • Coupling and model timestep: 10 mins per timestep
  • Simulation results: /p/project1/cslts/rigor1/TSMP2_exp/simexp_ideal_fs-eclmcurv_icon-eclm-parflow/run/sim_pft00-sid02-sv06_eclmparflow_20150701

Pressure head errors (mm)

# namcouple specification
PFL_PSI ECLM_PSI 1 600 1 pfl_psi.nc EXPORTED
70 70 70 70 gpfl gclm SEQ=1
P 0 P 0
LOCTRANS
INSTANT

# Pseudocode for computing pressure head errors
for each timestep:
  for each soil_layer:
    pressure_errors = eclm_nc["PFL_PSI_GRC"]/1000.0 - parflow_nc["pressure"] # resulting array shape is (70,70) 
Image

Soil liquid errors (mm)

# namcouple specification
PFL_SOILLIQ ECLM_SOILLIQ 1 600 1 pfl_sat.nc EXPORTED
70 70 70 70 gpfl gclm SEQ=1
P 0 P 0
LOCTRANS
INSTANT

# Pseudocode for computing soil liquid  errors
for each timestep:
  for each soil_layer:
    parflow_soil_liq = parflow_nc["saturation"]*parflow_static_nc["porosity"]*parflow_static_nc["DZ_Multiplier"]*1000.0
    soil_liq_errors = eclm_nc["PFL_SOILLIQ_GRC"]/1000.0 - parflow_soilliq_nc # resulting array shape is (70,70)
Image

Root ET errors (1/hr)

# namcouple specification
ECLM_ET PFL_ET 1 600 1 clm_flx.nc EXPORTED
70 70 70 70 gclm gpfl SEQ=2
P 0 P 0
LOCTRANS
INSTANT

# Pseudocode for computing root ET errors
for each timestep:
  for each soil_layer:
    soil_liq_errors = eclm_nc["QPARFLOW"] - parflow_nc["evaptrans"] # resulting array shape is (70,70)
Image

Remarks and next steps

These are preliminary results; I would have to triple-check the correctness of both the simulation and analysis. Moreover, I would postpone interpreting these trends and rather do another test run on a similar test case (e.g. NRW) and then generate these plots. Comparing coupling field behavior across different test cases may reveal a common pattern.

Activity

  1. s-poll commented on Sep 21, 2026

    @s-poll
    Member

    Thank you for this test. Please see the comments on the figures below.

    Time pairing: eCLM's history record t is the mean over the interval [t−1, t] hours. ParFlow's index t is the instantaneous state at t+1 hours. The trends you noticed (a daily cycle in layers 1–3 and a decay from the initial state at depth) reflect how quickly ParFlow's state is changing. A proposed rerun for a definitive test would be to set hist_nhtfrq = 1 with instantaneous output (hist_avgflag_pertape = 'I') in eCLM and set TimingInfo.DumpInterval = 1/6 in ParFlow.

    The ET plot does not show all layers. It repeats levels 5, 9 and 13, and drops 18–20. Please check your script. pft00 is bare soil, so QPARFLOW and evaptrans are exactly zero in layers 2–20. I would suggest changing the pft layer to test the root water update. This is especially important as transpiration in coupled runs seems to be systematically too low. This setup does not test grid aggregation, as only one column per grid cell is used here.

    PSI-Plot (minor): If I have read the script correctly, the PSI plot title should read (m). Please check also the discussion about PSI/SOILLIQ are exchanged over nlevgrnd instead of nlevsoi and the correspondent layer thickness for nlev > nlevsoi.

  2. kvrigor commented on Sep 22, 2026

    @kvrigor
    MemberAuthor

    Time pairing: eCLM's history record t is the mean over the interval [t−1, t] hours. ParFlow's index t is the instantaneous state at t+1 hours. The trends you noticed (a daily cycle in layers 1–3 and a decay from the initial state at depth) reflect how quickly ParFlow's state is changing. A proposed rerun for a definitive test would be to set hist_nhtfrq = 1 with instantaneous output (hist_avgflag_pertape = 'I') in eCLM and set TimingInfo.DumpInterval = 1/6 in ParFlow.

    Good catch; I've modified the sims to ensure that instantaneous field states were saved. Doing this for Parflow actually requires these 3 TCL switches to be the same: TimingInfo.BaseUnit, TimeStep.Value, and TimingInfo.DumpInterval.

    The ET plot does not show all layers. It repeats levels 5, 9 and 13, and drops 18–20.

    Fixed; I've already updated the plots in the 1st post.

    Lastly, here are the results for the NRW eCLM-Parflow test. Its main difference with the ideal test case is that it's running on BGC mode.

    NRW test case

    • Grid characteristics: 2D rectilinear, 300x300 gridcells, regional boundary conditions
    • OASIS interpolation algorithm: none; fields are passed 1-to-1 between eCLM and Parflow
    • Simulation duration and date: 24 hrs = 48 timesteps, 2017-07-01
    • Coupling and model timestep: 30 mins per timestep
    • eCLM BGC active?: yes
    • Simulation results: /p/project1/cslts/rigor1/eCLM_exp/NRW_eCLM-ParFlow

    Pressure head errors (mm)

    # namcouple specification
    PFL_PSI ECLM_PSI 1 1800 1 pfl_psi.nc EXPORTED
      300 300 300 300 gpfl gclm SEQ=1
      R 0 R 0
      LOCTRANS
      INSTANT
    
    # Pseudocode for computing pressure head errors
    for each timestep:
      for each soil_layer:
        pressure_errors = eclm_nc["PFL_PSI_GRC"]/1000.0 - parflow_nc["pressure"] # resulting array shape is (300,300) 
    
    Image

    Soil liquid errors (mm)

    # namcouple specification
    PFL_SOILLIQ ECLM_SOILLIQ 1 1800 1 pfl_sat.nc EXPORTED
      300 300 300 300 gpfl gclm SEQ=1
      R 0 R 0
      LOCTRANS
      INSTANT
    
    # Pseudocode for computing soil liquid  errors
    for each timestep:
      for each soil_layer:
        parflow_soil_liq = parflow_nc["saturation"]*parflow_static_nc["porosity"]*parflow_static_nc["DZ_Multiplier"]*1000.0
        soil_liq_errors = eclm_nc["PFL_SOILLIQ_GRC"]/1000.0 - parflow_soilliq_nc # resulting array shape is (300,300)
    
    Image

    Root ET errors (1/hr)

    # namcouple specification
    ECLM_ET PFL_ET 1 1800 1 eclm_qflx.nc EXPORTED
      300 300 300 300 gclm gpfl SEQ=2
      R 0 R 0
      LOCTRANS
      INSTANT
    
    # Pseudocode for computing root ET errors
    for each timestep:
      for each soil_layer:
        soil_liq_errors = eclm_nc["QPARFLOW"] - parflow_nc["evaptrans"] # resulting array shape is (300,300)
    
    Image
  3. kvrigor commented on Sep 22, 2026

    @kvrigor
    MemberAuthor

    Here's another TSMP2 test case originally set up by Carl Hartick back in 2023. Interestingly this EUR-11 test has been configured in BGC mode. The atmospheric forcings and initial condition data are likely to be outdated; still this is a valuable test as its land surface variability is the closest to the standard EUR-11 TSMP2 WFE setup. Ideally, the coupling behavior should be the same regardless of the test case, i.e. a coupled field mapped 1-to-1 should reflect in the simulation results.

    EUR11 test case

    • Grid characteristics: curvilinear, 444x432 gridcells, regional boundary conditions
    • OASIS interpolation algorithm: none; fields are passed 1-to-1 between eCLM and Parflow
    • Simulation duration and date: 24 hrs = 48 timesteps, 2017-03-01
    • Coupling and model timestep: 30 mins per timestep
    • eCLM BGC active?: yes
    • Simulation results: /p/project1/cslts/rigor1/TSMP2_exp/EUR-11_eCLM-ParFlow

    Pressure head errors (mm)

    # namcouple specification
    PFL_PSI ECLM_PSI 1 1800 1 pfl_psi.nc EXPORTED
      444 432 444 432 gpfl gclm SEQ=1
      R 0 R 0
      LOCTRANS
      INSTANT
    
    # Pseudocode for computing pressure head errors
    for each timestep:
      for each soil_layer:
        pressure_errors = eclm_nc["PFL_PSI_GRC"]/1000.0 - parflow_nc["pressure"] # resulting array shape is (444,432) 
    
    Image

    Soil liquid errors (mm)

    # namcouple specification
    PFL_SOILLIQ ECLM_SOILLIQ 1 1800 1 pfl_sat.nc EXPORTED
      444 432 444 432 gpfl gclm SEQ=1
      R 0 R 0
      LOCTRANS
      INSTANT
    
    # Pseudocode for computing soil liquid  errors
    for each timestep:
      for each soil_layer:
        parflow_soil_liq = parflow_nc["saturation"]*parflow_static_nc["porosity"]*parflow_static_nc["DZ_Multiplier"]*1000.0
        soil_liq_errors = eclm_nc["PFL_SOILLIQ_GRC"]/1000.0 - parflow_soilliq_nc # resulting array shape is (444,432)
    
    Image

    Root ET errors (1/hr)

    # namcouple specification
    ECLM_ET PFL_ET 1 1800 1 clm_flx.nc EXPORTED
      444 432 444 432 gclm gpfl SEQ=2
      R 0 R 0
      LOCTRANS
      INSTANT
    
    # Pseudocode for computing root ET errors
    for each timestep:
      for each soil_layer:
        soil_liq_errors = eclm_nc["QPARFLOW"] - parflow_nc["evaptrans"] # resulting array shape is (444,432)
    
    Image
  4. kvrigor commented on Sep 23, 2026

    @kvrigor
    MemberAuthor

    Some general trends I've noticed across all runs:

    1. Errors stay in the same order of magnitude as the values.
    2. Perfectly horizontal plots have zero perturbation; perhaps the converse also holds true, i.e. varying fields have a higher chance of errors? And per point 1, the error magnitude will be always the same as the magnitude of the field values?
    3. BGC mode runs (NRW and EU) exhibit more outliers than the idealized test case, which runs in SP mode.
    4. Error distributions across all plots vary, which suggests to me that
      • 1-to-1 coupling at least does not introduce systematic errors
      • errors are likely due to spatial heterogeneity and more prevalent in BGC mode

    With these short runs (24 hrs) it's hard to deduce how the error evolves over time; thus my next step is to lengthen the simulations to a monthly timescale. Also I need to further adapt the old EU11 test case to be as close to the standard EU setup.

    Plot interpretations and further debugging suggestions are welcome. :)

  5. DCaviedesV commented on Sep 24, 2026

    @DCaviedesV

    Lastly, here are the results for the NRW eCLM-Parflow test. Its main difference with the ideal test case is that it's running on BGC mode.

    I find it interesting that soil layers 18 and below show constant errors in soil liquid water and root uptake, but not in pressure.
    This poses two obvious questions:

    1. what changes from layer 17 to 18 (no more roots, maybe?)
    2. why does it not affect the time variation of the pressure error?

    Also pressure errors seem to be minimal in soil layers 15 and 16, but increase by an order of magnitude in 17 and 18. So the broad trend of smaller errors as you go deeper is not strictly monotonic.

    Presumably, the expectation might not be to have zero error because of the lagged coupling, right @s-poll ? And perhaps that explains the oscillatory behaviour with a positive error followed by a negative error in the next time step (which seems rather symmetrical in pressure, but not in the other variables). I guess a smaller coupling time step would improve that, should it not?

  6. AGonzalezNicolas commented on Sep 24, 2026

    @AGonzalezNicolas
    Contributor

    @kvrigor What is "median" on these plots? It seems to be equal to "0" on the plots.

  7. kvrigor commented on Sep 25, 2026

    @kvrigor
    MemberAuthor

    @kvrigor What is "median" on these plots? It seems to be equal to "0" on the plots.

    Following its standard definition, median is basically like the mean but tracks the actual "center-of-mass" of the distribution, which accounts for outliers. I didn't notice that median=0 on all plots (good observation!) and this is actually good news: this means that error=0 on most gridcells, implying that coupling works most of the time except for a few outliers. In other words, median != 0 would mean outliers/errors dominate and hence 1-to-1 coupling doesn't really work as expected.

    In my next round of experiments I'll include how many are these outliers (% of gridcells) and how are they spatially distributed across the domain.

  8. kvrigor commented on Sep 25, 2026

    @kvrigor
    MemberAuthor

    soil layers 18 and below show constant errors in soil liquid water and root uptake

    Also pressure errors seem to be minimal in soil layers 15 and 16, but increase by an order of magnitude in 17 and 18

    Sorry I forgot to mention: all plots show the state of the field received as-is by the target model and is not modified further. All plot data are based from gridcell-level quantities, and the fields that are actually modified in eCLM are the corresponding column-level quantities of the gridcell-level values. Hence observed errors should be fully attributed to the coupling logic itself and not due to physical processes. @s-poll this is also the same reason why differences in eCLM & Parflow porosities in my simulations does not matter for these coupling tests.

  9. AGonzalezNicolas commented on Oct 1, 2026

    @AGonzalezNicolas
    Contributor

    @kvrigor since you are plotting the median, it would also be useful to plot the 2-standard-deviation range, which covers approximately the 95% of the data. In other words, you could plot the 2.5th% and 97.5th% errors. If these two curves are close to the median (=0), that would indicate that most of the errors are small and make the outliers (and their error values) more apparent.

  10. kvrigor commented on Oct 2, 2026

    @kvrigor
    MemberAuthor

    @AGonzalezNicolas: the first set of plots are actually a time series of box plots where the standard deviations could have been visible, but clearly the graphic becomes too dense once we start accounting for time, which is what I'm mostly interested with. If you have a sample plot where std stats and its time evolution are both visible and legible, I'll revise my next set of plots!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    coupled-parflowIssues related to eCLM-ParFlow coupling

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions