Skip to content

Update User's Guide: Running CLM5.0 with irrigation #1640

Description

@samsrabin

The "Running with irrigation" section of the User's Guide contains incorrect instructions for CLM5.0. As described by @olyson in this DiscussCESM forum reply, the proper way to turn on irrigation is to set irrigate = .true. in the user_nl_clm namelist.

My suggestion is to have three separate subsections here, one for each of 4.0, 4.5, and 5.0.

Relevant to #509. Once that's implemented, the instructions for 5.0 will need to specify that irrigation is actually on by default for crop runs, but it can be turned off via the namelist.

Activity

  1. added
    documentationadditions or edits to user-facing documentation or its infrastructure
    on Feb 8, 2022
  2. added
    docs:updateSignificant update or fix needed to existing documentation
    docs-loc:users-guideRelates to User's Guide (using CTSM/tools)
    on May 29, 2025
  3. self-assigned this
    on Apr 2, 2026
  4. added
    nextthis should get some attention in the next week or two. Normally each Thursday SE meeting.
    on May 8, 2026
  5. samsrabin commented on May 8, 2026

    @samsrabin
    MemberAuthor

    I don't actually think it makes sense to maintain instructions for old versions of the code. In that case, this file would need to be changed to describe how to turn OFF irrigation in BgcCrop runs. At that point, do we even really need this file? Adding "next" to discuss.

  6. ekluzek commented on May 9, 2026

    @ekluzek
    Contributor

    Good idea on discussing this. It was needed when the behavior was different for clm4_0 and clm4_5/clm5_0. And it was needed when there was a special option to build-namelist to turn it on. Now with it being a simple namelist item it's no different than any other namelist item and hence may not be necessary.

    That said irrigation is off except for Bgc transient historical cases for clm5_0 or clm6_0. But, it can be turned on for SP cases for example. It's also off for CMIP6 SSP future scenarios,, So the defaults for when it's off or on aren't necessarily obvious, so it might be good to have this simple example of showing how to control it.

  7. samsrabin commented on May 10, 2026

    @samsrabin
    MemberAuthor

    Okay, well that's something we really need to talk about, because I think it should be ON by default for future scenarios! And probably for year-specific cases (e.g. 1850 and 2000) as well, although I can see why we'd want it off in 1850 for spinup purposes. But the "principle of least surprise" would suggest that if crops are on, irrigation should be on. (And since we have an irrigated generic crop, it should be on in non-Crop compsets too!)

  8. samsrabin commented on May 10, 2026

    @samsrabin
    MemberAuthor

    Regardless of what we decide on default behaviors for different compsets, the User's Guide should provide instructions for (1) checking what a case is set up to do and (2) toggling it.

    In addition to irrigate, also explain:

    • irrig_min_lai
    • irrig_start_time
    • irrig_length
    • irrig_target_smp
    • irrig_depth
    • irrig_threshold_fraction
    • irrig_river_volume_threshold
    • limit_irrigation_if_rof_enabled
    • use_groundwater_irrigation
    • irrig_method_default
  9. samsrabin commented on May 11, 2026

    @samsrabin
    MemberAuthor

    Also, we should document the various irrigation history outputs here.

  10. wwieder commented on May 28, 2026

    @wwieder
    Contributor

    this seems like a broader discussion what we want to support for CESM3 and CMIP7. @samsrabin will you create an issue to iron this out in how we're defining defaults and compsets? Then our documentation should reflect these decisions.

  11. added
    blocked: dependencyWait to work on this until dependency is resolved
    and removed
    nextthis should get some attention in the next week or two. Normally each Thursday SE meeting.
    on May 28, 2026
  12. samsrabin commented on May 28, 2026

    @samsrabin
    MemberAuthor

    Blocked until we resolve that (#4056).

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

Metadata

Metadata

Assignees

Labels

blocked: dependencyWait to work on this until dependency is resolveddocs-loc:users-guideRelates to User's Guide (using CTSM/tools)docs:updateSignificant update or fix needed to existing documentationdocumentationadditions or edits to user-facing documentation or its infrastructure

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions