ctsm5.4.055: Add temporal smoothing of DYNBAL conservation correction fluxes by billsacks · Pull Request #4189 · ESCOMP/CTSM

billsacks · 2026-08-31T23:04:31Z

Description of changes

Spread the DYNBAL water and energy fluxes over many years: Rather than releasing all of the DYNBAL fluxes in the year in which they're generated, instead put them in storage pools that are released with a 20-year residence time (controllable via a new namelist parameter). This reduces these fluxes, especially in the oscillatory case that is somewhat common with a dynamic ice sheet.

The new storage pools are reset when reset_dynbal_baselines is set to .true., since this feels conceptually similar to the other resetting done by that flag, so it feels appropriate to do this resetting at the same time.

This PR also changes the sign convention for the DYNBAL fluxes: the previous sign convention was unintuitively the opposite of the sign convention of other fluxes to river/atm; while I'm changing these fluxes anyway, I'm also flipping the sign convention to be more intuitive and hopefully less error-prone.

I have evaluated the changes here by examining QFLX_ICE_DYNBAL, QFLX_LIQ_DYNBAL and EFLX_DYNBAL, FSH_TO_COUPLER, QRUNOFF_ICE_TO_COUPLER and QRUNOFF_TO_COUPLER in 3 cases with compset I1850Clm60BgcCropG at resolution f09_g17:

A baseline case
The new code, out-of-the-box - residence time 20 years
The new code, with residence time set at 1 year

Specific notes

Contributors other than yourself, if any:

Much of the code was written by Claude code. However, I gave detailed guidance and carefully reviewed all code changes.

CTSM issues resolved or otherwise addressed, if any:

Partially addresses Consider one or more changes to reduce DYNBAL fluxes (dynamic landunit conservation correction fluxes) #4188 (specifically, option (1) in that issue)

If answers are expected to change, describe (delete this line otherwise):

Changes answers for all cases with landcover change - Hist/SSP cases, CISM cases, and FATES cases
Changes in Satellite Phenology cases are limited to the DYNBAL fluxes and a few related variables, including liquid/ice runoff and sensible heat flux (which then impacts ROF state and fluxes)
Changes in BGC cases are more widespread, I think because of the feedback of VOLR on CH4. (I tested this by running a version of ERS_Ly3_P64x2.f10_f10_mg37.IHistClm50BgcCropG.derecho_intel.clm-cropMonthOutput with SROF and verified that diffs were then limited to just the expected variables.)
Also changes answers for some additional cases that start mid-year and use a restart file that has non-zero state in the dynbal dribblers, despite not having transient landcover themselves (since this PR removes these dribblers, so no longer has fluxes out of these dribblers in these cases). On derecho aux_clm, this impacts the tests ERS_D_Ld5_Mmpi-serial.1x1_mexicocityMEX.I1PtClm60SpRsGs.derecho_gnu.clm-CLM1PTStartDate, SMS_Ld12_Mmpi-serial.1x1_vancouverCAN.I1PtClm60SpRsGs.derecho_gnu.clm-output_sp_highfreq, and ERP_D_Ld5.f10_f10_mg37.I2000Clm60Sp.derecho_intel.clm-decStart--clm-nofireemis.

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

New namelist flag, dynbal_storage_residence_time

Testing planned or performed, if any:

Ran aux_clm on derecho. Most tests passed; I'll look into a couple of failures. Answers changed as noted above
Will run aux_clm on izumi

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):
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?: (c)

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: Made a small necessary change to the tech note.
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?: (b)

Rather than releasing all of the DYNBAL fluxes in the year in which they're generated, instead put them in storage pools that are released with a 20-year turnover time. This reduces these fluxes, especially in the oscillatory case that is somewhat common with a dynamic ice sheet. This partially addresses ESCOMP#4188 (specifically, option (1) in that issue).

I found the previous sign convention unintuitive. While I'm changing these fluxes anyway, I'm going to flip the sign convention to be more intuitive.

This feels conceptually similar to the other resetting done by reset_dynbal_baselines, so it feels like these should be reset at the same time. (This wasn't an issue before the changes on this branch that change the annual dribblers to pools with a residence time, because the annual dribblers would empty themselves by the end of each year.)

This will be unnecessary following ESCOMP/CTSM#4189. This testmod is currently unused, so it seems safe to bring this in even before that CTSM PR is merged, since the plan is to merge that PR soon.

wwieder · 2026-09-02T16:41:36Z

@billsacks when this is ready for review maybe this can be a paired review with @slevis-lmwg? I think we may want this in the CESM3_alpha10a tag?

billsacks · 2026-09-02T17:41:07Z

@slevis-lmwg - I feel this is ready for review. I'm still reviewing some test results, but from my initial look things looked basically good.

ekluzek · 2026-09-02T21:42:07Z

@billsacks when this is ready for review maybe this can be a paired review with @slevis-lmwg? I think we may want this in the CESM3_alpha10a tag?

I think you mean cesm3_0_alpha11a. We don't need this in beta10 as it's only changing transient cases, and beta10 is about 1850 and CPLHIST spinup. It would also further delay the beta10 tag.

The pic of the whiteboard from yesterday also agrees with this being in beta11 rather than beta10.

slevis-lmwg

@billsacks thank you for writing clear code and comments. I made minor suggestions and asked for confirmation of my understanding once or twice. I may get a bit more out of this PR from a paired review, but it also does not seem necessary. If you would rather meet, I would be open.

billsacks · 2026-09-02T22:08:05Z

I think you mean cesm3_0_alpha11a. We don't need this in beta10 as it's only changing transient cases, and beta10 is about 1850 and CPLHIST spinup. It would also further delay the beta10 tag.

The pic of the whiteboard from yesterday also agrees with this being in beta11 rather than beta10.

I'm not clear on the vision for the different beta tags, but as I just noted to @ekluzek - this is desired for the coupled spinup immediately following the land spinup - so probably around the end of next week.

…ting Remove unnecessary testmod setting ### Description of changes This will be unnecessary following ESCOMP/CTSM#4189. This testmod is currently unused, so it seems safe to bring this in even before that CTSM PR is merged, since the plan is to merge that PR soon. ### Specific notes Contributors other than yourself, if any: N/A Fixes: N/A User interface changes?: No Testing performed (automated tests and/or manual tests): None

wwieder · 2026-09-02T22:13:38Z

I think you mean cesm3_0_alpha11a. We don't need this in beta10 as it's only changing transient cases, and beta10 is about 1850 and CPLHIST spinup. It would also further delay the beta10 tag.
The pic of the whiteboard from yesterday also agrees with this being in beta11 rather than beta10.

I'm not clear on the vision for the different beta tags, but as I just noted to @ekluzek - this is desired for the coupled spinup immediately following the land spinup - so probably around the end of next week.

I agree with @billsacks here, I think this is something that's used in the CESM3 PI control runs as soon as is realistically possible. I'm also not really clear what that means for the staging of CESM alpha tags, but I thought it could be alpha10e based on one version of the plan I saw today?

ekluzek · 2026-09-03T03:42:37Z

I think you mean cesm3_0_alpha11a. We don't need this in beta10 as it's only changing transient cases, and beta10 is about 1850 and CPLHIST spinup. It would also further delay the beta10 tag.
The pic of the whiteboard from yesterday also agrees with this being in beta11 rather than beta10.

I'm not clear on the vision for the different beta tags, but as I just noted to @ekluzek - this is desired for the coupled spinup immediately following the land spinup - so probably around the end of next week.

I agree with @billsacks here, I think this is something that's used in the CESM3 PI control runs as soon as is realistically possible. I'm also not really clear what that means for the staging of CESM alpha tags, but I thought it could be alpha10e based on one version of the plan I saw today?

I don't have too strong of a sense if it should be in beta10 or beta11. I mainly didn't want to add more complexity to beta10. From the planning we talked about today, I don't think the MOM, CICE, CAM, and CTSM tags will be ready and in a cesm alpha tag for about 2 weeks. So unless they want to start another coupled segment without all of those in place, but just the DYNBAL tag in place -- I think it's either the tail end of beta10 (cesm3_0_alpha10d) or it's the beginning of beta11 (cesm3_0_alpha11a). I don't think there will be much of a difference between either option in terms of timing. It's just if it's in beta10, it WILL have had prebeta testing done on it, and if it's in beta11, it would have to WAIT for the prebeta testing of beta10 to happen.

I know Dave wanted to start by the 9th, based on what we talked about today, I think the 18th is a realistic timeline, with maybe a few days sooner if things go well. But, if things don't go great it probably slips into the next week after the 18th.

ekluzek

This is all great stuff, that will be good to have in place to counter the oscilitory behavior that's been seen. It's more or less transforming the dribblers that were fixed on a year return time to something with a flexible time (currently 20 years). But, it's also easy to change that time now.

I have a bunch of questions and comments. The most important ones are:

I think we should set clm5_0 physics to use a value of 0.75 to get similar behavior to how it worked previously
The long description in namelist_definition is very clear and very useful. But, I think for usability/accessability it should go somewhere else. I'm thinking the Tech Note.
I ask if we think we really want to remove the old dribblers?
IF we do want to remove the old dribblers the AnnualFluxDribbler module should be removed and the unit tests for it.
If we are removing unit tests -- shouldn't we add some for the new behavior?

I think some decisions might have been made to get something robust in place quickly. And that is probably what we need here. But, I think we might want to make sure we are good with all of them for long term? And if not we might want to plan some follow on refactoring of the most important things.

We should probably talk about some of this together as well. But, we probably don't want/need to do that until next week....

It's impossible to exactly recover the old behavior, but using a residence time somewhere between 0.5 year and 1.0 year gives something that roughly approximates the old behavior. So make that the default for clm5_0. Co-authored-by: Erik Kluzek <ekluzek@users.noreply.github.com>

Instead of a hard-coded 365, use get_average_days_per_year (both to avoid hard-coding 365, and to get a more correct value if we're running with a Gregorian calendar).

Now that namelist defaults recovers something close to the old clm5_0 behavior, I feel that this extra text in namelist definition is unnecessary.

ekluzek

@billsacks it looks like all review points were taken care of. So I resolved most of the conversations. The only one I left open was the one about the long (but clear) instructions in the namelist_definition file, in case you were going to do more with it. But, I would also be fine with your going ahead with it as is.

So approving. Are you planning on running the baselines on Derecho and Izumi and making the ChangeLog/ChangeSum files to close this one out?

Since, you are ready now, we could switch tag order and make this "55" and mine "56", which won't be ready on Friday anyway.

ekluzek · 2026-09-04T08:05:49Z

Oh, actually @billsacks it looks like @slevis-lmwg is assigned to this, so maybe he's going to finish the baselines for it? It would just be good if you start the ChangeLog file @billsacks.

@slevis-lmwg we are thinking of changing the tag order so this becomes "55" and goes next. I won't have a tag on master on Friday, so this could come in now.

ekluzek · 2026-09-04T16:32:20Z

@billsacks is going to take this all the way home and it's now next up in the tag queue.

The problem with the previous placement is that dynSubgridControlMod is initialized before the calendar is initialized. This new placement allows us to initialize this variable after the calendar is initialized. It also keeps the namelist variable local to where it's needed.

billsacks · 2026-09-04T19:26:50Z

I have confirmed that the recent change to move the namelist variable is bit-for-bit with the previous version of this branch, by running ERS_Ly3_P64x2.f10_f10_mg37.IHistClm50BgcCropG.derecho_intel.clm-cropMonthOutput.

Also, test the new zeroing of the dynbal storage terms in this unit test.

When the RUN fails, the COMPARE_base_rest is left in a PEND state

ekluzek

Some comments about handling file units with newunit, and about endrun.

ekluzek · 2026-09-04T23:38:04Z

+    ! !USES:
+    use shr_const_mod  , only : SHR_CONST_CDAY
+    use abortutils     , only : endrun
+    use fileutils      , only : getavu, relavu


Remove these. See below...

#1423 talks about this.

ekluzek · 2026-09-04T23:41:00Z

+    dynbal_storage_residence_time = 0._r8
+
+    if (masterproc) then
+       nu_nml = getavu()


You can remove the old unit processing things we had. Fortran now allows you to use a new unit keyword in the open statement to give you a free unit.

I'd like to move to that pattern so we can remove the unit processing stuff.

ekluzek · 2026-09-04T23:44:07Z

+       if (nml_error == 0) then
+          read(nu_nml, nml=dyn_cons_biogeophys_inparm, iostat=nml_error)
+          if (nml_error /= 0) then
+             call endrun(msg='ERROR reading dyn_cons_biogeophys_inparm namelist'//errMsg(sourcefile, __LINE__))


You can now remove the bit about errMsg and pass file and line options directly in the endrun call. It's a little less cumbersome.

#1452 talks about this

ekluzek · 2026-09-04T23:44:58Z

+          call endrun(msg='ERROR finding dyn_cons_biogeophys_inparm namelist'//errMsg(sourcefile, __LINE__))
+       end if
+       close(nu_nml)
+       call relavu( nu_nml )


This can be removed with the newunit option to open.

ekluzek · 2026-09-04T23:45:37Z

+             call endrun(msg='ERROR reading dyn_cons_biogeophys_inparm namelist'//errMsg(sourcefile, __LINE__))
+          end if
+       else
+          call endrun(msg='ERROR finding dyn_cons_biogeophys_inparm namelist'//errMsg(sourcefile, __LINE__))


Same thing here. Line and file can be used as arguments directly in endrun.

ekluzek · 2026-09-04T23:50:50Z

+    integer :: nu_nml    ! unit for namelist file
+    integer :: nml_error ! namelist i/o error flag
+
+    character(len=*), parameter :: subname = 'dynConsBiogeophys_readnl'


I suggest removing this. With the file and line options to endrun I've found this not useful. And it has the possibility of changing the subroutine name and forgetting to change this. So it has a maintenance burden that file and line to endrun don't have.

billsacks added 5 commits August 28, 2026 16:37

Change sign convention for water and energy dynbal fluxes and storage

9681949

I found the previous sign convention unintuitive. While I'm changing these fluxes anyway, I'm going to flip the sign convention to be more intuitive.

Make dynbal storage residence time namelist controllable

975d410

Update tech note for changes on this branch

bf025d7

ekluzek added non-b4b Changes answers (incl. adding tests) enhancement new capability or improved behavior of existing capability next this should get some attention in the next week or two. Normally each Thursday SE meeting. science Enhancement to or bug impacting science labels Sep 1, 2026

billsacks mentioned this pull request Sep 1, 2026

Remove unnecessary testmod setting ESCOMP/CESM#420

Merged

wwieder moved this to In progress - master in CTSM: Upcoming tags Sep 2, 2026

wwieder added this to CTSM: Upcoming tags Sep 2, 2026

wwieder requested a review from slevis-lmwg September 2, 2026 16:40

ekluzek added this to the cesm3_0_beta11 (compset) milestone Sep 2, 2026

slevis-lmwg approved these changes Sep 2, 2026

View reviewed changes

Comment thread doc/source/tech_note/Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst Outdated

Comment thread src/dyn_subgrid/dynSubgridControlMod.F90 Outdated

Comment thread src/main/lnd2atmMod.F90

Add a note in namelist definition

1eee35d

ekluzek changed the title ~~Add temporal smoothing of DYNBAL conservation correction fluxes~~ ctsm5.4.056: Add temporal smoothing of DYNBAL conservation correction fluxes Sep 3, 2026

ekluzek requested changes Sep 3, 2026

View reviewed changes

github-project-automation Bot moved this from In progress - master to Stalled (needs review, blocked etc.) in CTSM: Upcoming tags Sep 3, 2026

ekluzek moved this from Stalled (needs review, blocked etc.) to In progress - master in CTSM: Upcoming tags Sep 3, 2026

wwieder assigned slevis-lmwg Sep 3, 2026

wwieder removed the next this should get some attention in the next week or two. Normally each Thursday SE meeting. label Sep 3, 2026

ekluzek reviewed Sep 3, 2026

View reviewed changes

Comment thread bld/namelist_files/namelist_defaults_ctsm.xml Outdated

slevis-lmwg added this to LMWG: Sprint Planning Board Sep 3, 2026

github-project-automation Bot moved this to Todo in LMWG: Sprint Planning Board Sep 3, 2026

billsacks and others added 5 commits September 3, 2026 15:21

Don't use hard-coded 365 days per year

e5768b9

Instead of a hard-coded 365, use get_average_days_per_year (both to avoid hard-coding 365, and to get a more correct value if we're running with a Gregorian calendar).

Remove a note from namelist definition

54ff1fe

Now that namelist defaults recovers something close to the old clm5_0 behavior, I feel that this extra text in namelist definition is unnecessary.

Add a comment describing clm5 default for dynbal_storage_residence_time

223b6e7

More comments on default values for dynbal_storage_residence_time

3f516e8

ekluzek approved these changes Sep 4, 2026

View reviewed changes

ekluzek changed the title ~~ctsm5.4.056: Add temporal smoothing of DYNBAL conservation correction fluxes~~ ctsm5.4.055: Add temporal smoothing of DYNBAL conservation correction fluxes Sep 4, 2026

ekluzek assigned billsacks and unassigned slevis-lmwg Sep 4, 2026

billsacks added 2 commits September 4, 2026 11:07

Move some description out of namelist definition into tech note

2195552

billsacks added 2 commits September 4, 2026 15:37

Fix test_dyn_cons_biogeophys unit tests

1e56fd6

Also, test the new zeroing of the dynbal storage terms in this unit test.

Add some tests to expected fails

cf37d1a

When the RUN fails, the COMPARE_base_rest is left in a PEND state

ekluzek approved these changes Sep 5, 2026

View reviewed changes

Uh oh!

Conversation

billsacks commented Aug 31, 2026

Description of changes

Specific notes

Requirements before merge:

Uh oh!

wwieder commented Sep 2, 2026

Uh oh!

billsacks commented Sep 2, 2026

Uh oh!

ekluzek commented Sep 2, 2026

Uh oh!

slevis-lmwg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

billsacks commented Sep 2, 2026

Uh oh!

wwieder commented Sep 2, 2026

Uh oh!

ekluzek commented Sep 3, 2026

Uh oh!

ekluzek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ekluzek left a comment

Choose a reason for hiding this comment

Uh oh!

ekluzek commented Sep 4, 2026

Uh oh!

ekluzek commented Sep 4, 2026

Uh oh!

billsacks commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ekluzek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

billsacks commented Sep 4, 2026 •

edited

Loading